DEV Community: Solon Framework

The AppContext API: Programmatic Bean Control in Solon

Solon Framework — Thu, 06 Aug 2026 01:48:31 +0000

Annotations get you a long way in Solon. @Component, @Inject, @Bean cover the everyday work: declare a bean, wire it, done. But the moment you start writing a plugin, a framework extension, or anything that has to touch the container at runtime, you drop below the annotation layer. That layer is AppContext.

AppContext is the core component of Solon. It's where IoC/AOP actually lives, and it's the foundation the framework's hot-plug capability is built on. Its job is simple to state: manage the beans it holds, and register/apply the annotation processors that produce them. This post walks through the programmatic side of it, the API you reach for when annotations aren't enough.

Getting hold of an AppContext

There are three ways to get a reference, depending on where you are.

Global, from anywhere:

import org.noear.solon.Solon;

public class DemoClass {
    UserService userService;

    public void demo() {
        Solon.context().getBeanAsync(UserService.class, bean -> {
            userService = bean;
        });
    }
}

Injected into a component:

import org.noear.solon.annotation.Component;
import org.noear.solon.annotation.Inject;
import org.noear.solon.core.AppContext;

@Component
public class DemoComponent {
    @Inject
    AppContext context;
}

Handed to a plugin at the start of its lifecycle:

import org.noear.solon.core.AppContext;
import org.noear.solon.core.Plugin;

public class DemoPlugin implements Plugin {
    @Override
    public void start(AppContext context) {
        //...
    }
}

The plugin variant is the one that matters most for extension work: Plugin.start(AppContext) is your entry point into the container before the application is fully wired.

The container is async-ready, and that changes how you fetch

Notice the first example used getBeanAsync, not getBean. That's deliberate.

Solon builds its container as beans become available, not all at once up front. If you call getBean(SomeType.class) too early, the bean may simply not be there yet and you get back null. The official docs flag this as a matter of timing. The async fetch methods are the answer: they hand you the bean the moment it's ready, whether that's now or a few beans later.

// Fires whenever UserService becomes available, no null surprises
Solon.context().getBeanAsync(UserService.class, bean -> {
    // use bean here
});

Two families exist for this:

getBeanAsync(name, callback) / getBeanAsync(type, callback) — receive a single bean when ready
subBeansOfType(baseType, callback) — receive every bean of a base type as they arrive

There's a matching pair at the wrapper level: getWrapAsync(nameOrType, callback) and subWrapsOfType(baseType, callback). More on wrappers below.

If you know the bean already exists by the time your code runs, the synchronous getBean(name) and getBean(type) are fine. The rule of thumb: inside plugin start or during early wiring, prefer async; well after startup, synchronous is fine.

baseType vs type: a batch or a single one

Several methods come in two shapes, one that takes a baseType and one that takes a type. This isn't redundancy, it's a deliberate trade-off.

With OfType	Without OfType
`getWrapsOfType(baseType) -> List[T]`	`getWrap(type) -> T`
`subWrapsOfType(baseType, callback)`	`getWrapAsync(type)`
`getBeansOfType(baseType) -> List[T]`	`getBean(type) -> T`
`subBeansOfType(baseType, callback)`	`getBeanAsync(type)`
`getBeansMapOfType(baseType)`	/

baseType matches by base class and returns a batch. The method names carry an s (plural). You get every matching bean, at some cost to lookup speed.
type matches the concrete type by hash code and returns a single bean. Faster, but exactly one.

The design follows Solon's restraint principle: pick the one that fits what you actually need, rather than always reaching for the broad query. Need all implementations of an interface? getBeansOfType. Need one specific bean fast? getBean.

There's also getBeansMapOfType(baseType), which returns a Map[String, T] keyed by bean name, and getBeanOrNew(type), which fetches or creates on the spot.

Manual assembly: putting objects into the container at runtime

This is the part annotations can't do. When you build an object yourself and want the container to own it, you wrap it.

// wrap and push into the container in one step
context.wrapAndPut(UserService.class, new UserServiceImpl());

The wrapping API:

wrap(type), wrap(type, bean), wrap(type, bean, typed) — produce a BeanWrap
wrap(name, bean), wrap(name, bean, typed)
wrap(name, type) and wrap(name, type, typed) — supported since v3.0
wrapAndPut(type), wrapAndPut(type, bean), wrapAndPut(type, bean, typed) — wrap and push into the container
wrapAndPut(name, bean), wrapAndPut(name, bean, typed) — supported since v3.0
putWrap(name, wrap), putWrap(type, wrap) — push an existing wrap into the bean store
hasWrap(nameOrType) — check whether a wrap exists
beanRegister(wrap, name, typed) — register a wrap (the fuller version of putWrap)

And a critical detail. If you wrap a bean manually and expect type subscribers (subBeansOfType / subWrapsOfType) to notice it, they won't automatically. Per the docs:

By default, beans produced by @Bean or @Component are published automatically. Otherwise you must call the publish method (beanPublish) manually.

So the manual path is: wrap it, then publish it.

BeanWrap wrap = context.wrap(UserService.class, new UserServiceImpl());
context.putWrap(UserService.class, wrap);
context.beanPublish(wrap);  // now subWrapsOfType subscribers fire

Two related methods round this out: beanDeliver(wrap) hands a special-interface bean off to its manager, and beanInject(bean) runs injection on an object you created yourself so its @Inject fields get filled.

Walking the container

When you need to inspect what's registered, there are iteration and lookup helpers. The docs note these are timing-sensitive, so run them once the container is settled:

beanForeach((name, wrap) -> {}) and beanForeach((wrap) -> {}) — iterate the wrap store
beanFind((name, wrap) -> bool) -> List[BeanWrap] and beanFind((wrap) -> bool) -> List[BeanWrap] — find matching wraps

Registering your own annotation handlers

The other half of AppContext is annotation processing. This is how Solon lets you teach the container about a custom annotation, the same mechanism the framework uses internally.

beanBuilderAdd(anno, builder) and beanBuilderAdd(anno, targetClz, builder) — handle how an annotation builds a bean
beanInjectorAdd(anno, injector) and beanInjectorAdd(anno, targetClz, injector) — handle how an annotation injects
beanExtractorAdd(anno, extractor) and beanExtractorHas(anno) — handle extraction
beanInterceptorAdd(anno, interceptor), beanInterceptorAdd(anno, interceptor, index), beanInterceptorGet(anno) — attach an interceptor to an annotation (AOP)

Registered inside Plugin.start, these let a plugin introduce a brand-new annotation that behaves like a first-class citizen of the container. That's the seam a lot of Solon's ecosystem plugins hook into.

For scanning and construction there's also beanScan(source) / beanScan(basePackage) / beanScan(classLoader, basePackage) to bring a package's beans in, and beanMake(clz) to construct a single bean with full processing applied.

Binding lifecycle

Finally, if a bean needs to react to container lifecycle events, register it:

lifecycle(lifecycleBean)
lifecycle(index, lifecycleBean) — with ordering

This is the programmatic equivalent of implementing LifecycleBean, useful when the object you want to hook in wasn't declared as a component.

Where this fits

AppContext is the layer beneath the annotations, and it's what makes the rest of the kernel's open capabilities possible. The lifecycle timing points, the E-Spi external extensions and H-Spi hot-plug modules, they all lean on this same interface to register, publish, and tear down beans at runtime. If annotations are how you declare your application, AppContext is how you program the container underneath it.

The full method reference lives in the official docs at solon.noear.org. Everything above is the subset you actually reach for when you step past annotations.

Solon Plugins Beyond the Fatjar: External Extension (E-Spi) and Hot-Plug (H-Spi)

Solon Framework — Wed, 05 Aug 2026 12:12:10 +0000

You shipped a Solon service as a single fatjar. Then reality shows up: ops wants to point the datasource at a different host without asking you to rebuild, and the business team wants to take one module offline at 2 a.m. without bouncing the whole process. If your only answer is "repackage and redeploy the whole jar," you feel the friction every time.

Solon has two mechanisms built exactly for this seam: E-Spi (external extension) and H-Spi (hot-plug). They sit at different points on the same spectrum, and picking the wrong one costs you either flexibility or stability. Here is how each works and when to reach for which. Everything below is on v4.0.4.

The shared problem: a fatjar is sealed

A fatjar is convenient to deploy and miserable to amend. Config files, business modules, everything is baked in. E-Spi and H-Spi both crack that seal, but with very different contracts:

E-Spi lets you place config files and plugin jars outside the fatjar, loaded at startup into the same runtime. Simple, no extra dependency, but changes require a restart.
H-Spi gives each plugin its own isolated ClassLoader and lets you start and stop modules while the service keeps running. More power, more responsibility.

E-Spi: put config and modules beside the jar

E-Spi (external extension) targets the fatjar deployment case directly. You designate an extension directory; at startup Solon scans it and loads what it finds:

.properties / .yml files are loaded as extension config
.jar / .zip files are loaded as plugin packages

Step 1 — declare the extension directory

# extension directory is demo_ext (no error if it doesn't exist)
solon.extend: "demo_ext"

Prefix the value with ! and Solon creates the directory for you:

# extension directory is demo_ext (! means auto-create)
solon.extend: "!demo_ext"

Step 2 — drop files next to the jar

demo.jar
demo_ext/_db.properties
demo_ext/demo_user.jar
demo_ext/demo_order.jar

Now the datasource config lives in _db.properties outside the jar, and two business modules ride along as separate plugin jars. Ops can edit that properties file directly; you never touch the fatjar.

Step 3 (optional) — load programmatically

If you'd rather load extras in code, the kernel exposes it directly:

@SolonMain
public class Application {
    public static void main(String[] args) throws Exception {
        Solon.start(Application.class, args, app -> {
            // load a package file
            app.classLoader().addJar(new File("/demo.jar"));

            // load a properties file
            app.cfg().loadAdd(new File("/demo.yml"));
        });
    }
}

Under the hood, this is AppClassLoader.addJar(URL | File). That single detail explains E-Spi's whole personality:

Everything is shared — all plugin packages share one ClassLoader, one AppContext, one config tree
Split or merged, your call — package externally, or bundle with the main app; loading timing is the same either way
Updates need a restart — because it all rides one ClassLoader loaded at boot, swapping a jar or editing config only takes effect after restarting the main service
No extra dependency — the kernel provides E-Spi directly

One packaging note: a plugin jar should either be built as a fatjar itself, or have its dependencies folded into the main app (common dependencies especially belong in the main app's build, with the plugin's own pom marking them optional).

Official example: demo2002-external_ext (under 2.Solon_Advanced in the solon-examples repo).

H-Spi: isolate and hot-swap without a restart

H-Spi (hot-plug) is the heavier tool. You develop one business module as a self-contained plugin package, and the running service can load and unload it live. The defining difference from E-Spi is isolation:

Each plugin gets its own ClassLoader, AppContext, and config — fully isolated
Need the main app's global resources? Grab them explicitly via Solon.app(), Solon.cfg(), Solon.context()
Updating a plugin package does not require restarting the main service
The main app must pull in the solon-hotplug dependency to manage business plugin packages

The ClassLoader contract

Isolation is the whole point, so the class-visibility rules matter:

Parent ClassLoader (put common resources here): children can see and use its classes and resources — but anything a child registers must be unregistered in its stop event
Sibling ClassLoaders: cannot use each other's classes or resources. Don't wire explicit type interactions between siblings; talk through the event bus instead, passing data as parent-level entity classes or weakly-typed JSON — treat it like calling a remote API

Write start(), and write stop() honestly

A hot-pluggable plugin implements Plugin. start registers what the module needs; stop must remove every resource it registered, or you leak on unload:

public class Plugin1Impl implements Plugin {
    AppContext context;
    StaticRepository staticRepository;

    @Override
    public void start(AppContext context) {
        this.context = context;

        // add my own config file
        context.cfg().loadAdd("demo1011.plugin1.yml");
        // scan my own beans
        context.beanScan(Plugin1Impl.class);

        // add my own static file repository (register the classloader)
        staticRepository = new ClassPathStaticRepository(context.getClassLoader(), "plugin1_static");
        StaticMappings.add("/html/", staticRepository);
    }

    @Override
    public void stop() throws Throwable {
        // remove http handlers (use a prefix to make removal easy)
        Solon.app().router().remove("/user");

        // remove scheduled jobs (pick a job impl that supports manual removal)
        JobManager.getInstance().jobRemove("job1");

        // remove event subscriptions
        context.beanForeach(bw -> {
            if (bw.raw() instanceof EventListener) {
                EventBus.unsubscribe(bw.raw());
            }
        });

        // remove the static file repository
        StaticMappings.remove(staticRepository);
    }
}

That stop method is the tax for hot-plug. Routes, jobs, event subscriptions, static repositories — if start added it, stop removes it. Skip a line and you get ghost routes or leaked listeners after unload.

Template rendering has one more ClassLoader gotcha — the renderer must be pinned to the right ClassLoader:

public class BaseController implements Render {
    // account for the classloader where templates live
    static final FreemarkerRender viewRender = new FreemarkerRender(BaseController.class.getClassLoader());

    @Override
    public void render(Object data, Context ctx) throws Throwable {
        if (data instanceof Throwable) {
            throw (Throwable) data;
        }
        if (data instanceof ModelAndView) {
            viewRender.render(data, ctx);
        } else {
            ctx.render(data);
        }
    }
}

For cross-module communication, lean on the event bus with weakly-typed payloads (Map / JSON string); DamiBus pairs well here for decoupling. Official example package: demo1011. Plugin management can be pushed further into a repository or platform via solon-hotplug.

Side by side

Dimension	E-Spi	H-Spi
ClassLoader / AppContext / config	shared	isolated (fully)
Restart after update?	yes	no (hot update)
Extra dependency	none (kernel built-in)	solon-hotplug
Focus	simple external extension / config edits	isolation + hot-plug + management
Resource removal	nothing special	must manually remove all registered resources in `stop`
Cross-module comms	direct sharing	event bus / weakly-typed data
Underlying mechanism	`AppClassLoader.addJar`	isolated ClassLoader + `Plugin.start/stop`

Which one do you actually need

Start with the question "does this have to change without a restart?"

No, a restart window is fine. Use E-Spi. Externalizing datasource config and shipping business modules as sibling jars covers most "I don't want to rebuild the fatjar" cases, with zero extra dependency and no lifecycle bookkeeping.
Yes, the service must stay up while a module comes and goes. Use H-Spi. You get true isolation and live swap, and in return you accept the stop-cleanup discipline and event-bus-only cross-module contract.

A useful mental model: E-Spi moves files outside the jar; H-Spi moves modules into their own runtime bubbles. One is about deployment convenience, the other about operational isolation. Plenty of teams run both — E-Spi for externalized config, H-Spi for the one or two modules that genuinely need hot swap.

If you're deciding how to structure a Solon service for the long haul, it's worth reading both official pages end to end before you commit — the ClassLoader rules in particular reward a careful first read.

What does your fatjar most need to shed first: config, or whole modules?

SolonCode v2026.8.4: Adjustable UI Fonts, 22 Languages, and Smarter Memory Search

Solon Framework — Wed, 05 Aug 2026 08:54:00 +0000

A fully Chinese-capable coding agent that goes to work the moment you open a terminal. This release rounds out three things at once: read it clearly, use your own language, and actually find what it remembered.

What is SolonCode

SolonCode is an enterprise-grade terminal coding agent built by Hangzhou Noear Technology — a digital teammate that understands requirements, plans steps, and writes code on its own. It's not picky about models or platforms, and a single curl line gets you running.

Repos: Gitee · GitCode · GitHub

Install

Runs on Java 8+ (8~26), across macOS / Linux / Windows / Harmony PC.

# 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

For the first run, start soloncode web 0 (0 picks a random port; you can also pin one, e.g. soloncode web 1212), then head to Settings → Models to add a model and test the connection.

Three reasons to upgrade

1. Adjustable UI fonts — no more squinting through long sessions

Settings → General → Fonts adds three independent controls: UI Font (12 searchable options), Code Font (independent from the UI font), and Font Scale (85%–150%, 5% steps, with a one-click reset).

Changes apply instantly, no restart needed. The scaling decouples type size from layout — when you enlarge text, fixed-size elements like icons, borders, and control heights don't get stretched out of shape. That's something full-page browser zoom could never do cleanly.

2. 22 UI languages — overseas developers land on their native tongue

Settings → General → Display Language offers Follow System + 22 languages, covering Simplified and Traditional Chinese, English, Japanese, Korean, German, French, Spanish, Italian, Russian, and Portuguese — plus less common ones like Arabic, Bengali, Bosnian, and Norwegian. It's not a token English-Japanese-Korean gesture. The default follows your system, so overseas developers land on a native interface right after install.

Two notes: the UI language is independent from the model's reply language — switching to English only changes the interface text. And in this version the language choice isn't persisted yet (a refresh reverts to Follow System); this has been reported to the core team.

3. Memory — from "can store" to "can find again"

Memory took shape across four releases: v2026.7.27 added the web management panel, v2026.7.28 introduced scopes (shared cross-project knowledge goes to "User Global," project-specific conventions go to "Current Workspace," and switching projects keeps them from interfering), and v2026.8.4 refined the prompting and search.

Search targets a real pain point: once you have hundreds of entries, "stored but unfindable" is as good as not stored. Now you can browse by importance and time, and use semantic retrieval to pinpoint what you need.

While we're at it: engineering touch-ups

The web workbench keeps growing into a serious tool: sub-agent management (v2026.7.24, four built-ins — bash / explore / general / plan, none with write access except general; drawing that boundary in config is more reliable than leaning on prompts), context-compaction threshold as a ratio (v2026.7.26, default 75%, no recalculating when you swap models), a simplified /goal command, an enhanced Git review panel (diff/stat, rollback, directory detection, garbled-Chinese fix), config reload (no restart across instances), skins, and the continuously iterating desktop build.

Appendix: v2026.8.4 changelog

Added the soloncode web font adjustment feature
Improved SolonCode memory prompting and search

Full history is in the project repo CHANGELOG.

Solon's Application Lifecycle: 12 Timing Points, LifecycleBean, EventBus and Plugin SPI

Solon Framework — Wed, 05 Aug 2026 07:10:29 +0000

Most framework bugs I have chased in Java web apps were not logic bugs. They were timing bugs: a bean that read config before the config was loaded, a listener that subscribed after the event had already fired, a connection pool that closed while requests were still draining.

Solon is explicit about this. The docs lay out the whole application lifecycle as a fixed set of timing points, and every extension mechanism in the framework hangs off one of them. Once you can name the points, "when does my code run" stops being guesswork.

Here is the model, with the four hooks you actually write against.

The lifecycle, counted

The official breakdown is one init callback + six application events + three plugin timing points + two container timing points.

The init callback is the lambda you pass to Solon.start:

import org.noear.solon.Solon;
import org.noear.solon.annotation.SolonMain;

@SolonMain
public class App {
    public static void main(String[] args) {
        Solon.start(App.class, args, app -> {
            // application init timing point
        });
    }
}

The six application events, in order:

Event	Meaning	Note
`AppInitEndEvent`	init finished	manual subscription only
`AppPluginLoadEndEvent`	plugin loading finished	manual subscription only
`AppBeanLoadEndEvent`	bean scan finished
`AppLoadEndEvent`	startup finished
`AppPrestopEndEvent`	pre-stop
`AppStopEndEvent`	stopped	since v2.1.0

All of them live in org.noear.solon.core.event.

Two warnings from the docs are worth repeating, because both are easy to trip over:

Do not block the startup thread. The app only runs normally after startup completes. A blocking call in an init hook will hang the whole boot.

Events before AppBeanLoadEndEvent must be subscribed before startup. By the time class scanning happens, AppInitEndEvent and AppPluginLoadEndEvent have already fired. An annotated listener discovered during the scan is simply too late. For those two you subscribe manually:

import org.noear.solon.Solon;
import org.noear.solon.annotation.SolonMain;
import org.noear.solon.core.event.AppInitEndEvent;

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

For anything from AppBeanLoadEndEvent onward, the annotated form works:

import org.noear.solon.annotation.Component;
import org.noear.solon.core.event.AppLoadEndEvent;
import org.noear.solon.core.event.EventListener;

@Component
public class AppLoadEndEventListener implements EventListener<AppLoadEndEvent> {
    @Override
    public void onEvent(AppLoadEndEvent event) throws Throwable {
        // event.app();
    }
}

That "subscribe early or miss it" rule is the whole reason the event list is worth memorizing. It is not a quirk, it is a consequence of the container scanning classes exactly once.

LifecycleBean: four methods, two annotations

For ordinary beans you rarely need raw events. LifecycleBean binds your bean to the container's start and stop:

Interface method	Annotation	Runs at
`start()`	`@Init`	`AppContext::start()`
`postStart()`		same, later half (since v2.9)
`preStop()`		`AppContext::preStop()` (since v2.9)
`stop()`	`@Destroy`	`AppContext::stop()` (since v2.2.0)

import org.noear.solon.annotation.Component;
import org.noear.solon.core.bean.LifecycleBean;

@Component
public class DemoCom implements LifecycleBean {
    @Override
    public void start() {
        // bean scan is done here, do initialization
    }

    @Override
    public void postStart() {
        // start remote services; do NOT create new managed beans here
    }

    @Override
    public void preStop() {
        // deregister from discovery, etc.
    }

    @Override
    public void stop() {
        // release local resources
    }
}

If you only need start(), the annotation is shorter:

import org.noear.solon.annotation.Component;
import org.noear.solon.annotation.Init;

@Component
public class Demo {
    @Init
    public void init() { // any no-arg method name
    }
}

Same for @Destroy in place of stop().

Three constraints that matter in real code:

The constructor is the wrong place for initialization. At ::new() the bean has been constructed but is not yet registered in the container, and injected fields are not populated. Use constructor-parameter injection, or @Init.

postStart() cannot create managed beans. It is the tail end of startup, meant for kicking off tasks and network listeners.

LifecycleBean only applies to singletons. For non-singletons, only the first instance produced during the scan is managed; the lifecycle of other instances is on you.

Ordering without ceremony

Since v2.2.8, LifecycleBean instances are ordered automatically, and the ordering comes from injection dependencies. If Bean2 injects Bean1, then Bean1.start() runs first:

@Component
public class Bean1 implements LifecycleBean {
    @Override
    public void start() {
        // db1 init ...
    }

    public void func1() {
        // db1 call
    }
}

@Component
public class Bean2 implements LifecycleBean {
    @Inject
    Bean1 bean1;

    @Override
    public void start() {
        bean1.func1();
    }
}

The docs call out the useful trick here: even when two beans have no natural dependency, adding an injection creates one, and ordering follows for free.

The flip side is that mutual injection between two LifecycleBeans makes the sort unsolvable and you get a circular-dependency error. Two ways out: drop the mutual dependency, or pin the order explicitly with @Component(index = 1) / @Component(index = 2).

If a dependency simply is not ready during start() — some beans are only produced at AppContext.start() time — move that work to an AppLoadEndEvent listener instead.

EventBus: strongly typed, synchronous, transaction-friendly

The lifecycle events above ride on the same in-process bus you can use for your own events. Three properties define it: strongly typed events, publish/subscribe, and synchronous dispatch that propagates exceptions — which is what makes transaction rollback work across a publish.

@Getter
public class HelloEvent {
    private String name;
    public HelloEvent(String name) {
        this.name = name;
    }
}

Subscribe either way:

import org.noear.solon.annotation.Component;
import org.noear.solon.core.event.EventBus;
import org.noear.solon.core.event.EventListener;

@Component
public class HelloEventListener implements EventListener<HelloEvent> {
    @Override
    public void onEvent(HelloEvent event) throws Throwable {
        System.out.println(event.getName());
    }
}

// or manually
EventBus.subscribe(HelloEvent.class, event -> {
    System.out.println(event.getName());
});

Publish:

@Component
public class DemoService {
    public void hello(String name) {
        EventBus.publish(new HelloEvent(name));           // synchronous
        // EventBus.publishAsync(new HelloEvent(name));    // generally not recommended
    }
}

The docs are direct about publishAsync: generally not recommended, because it cannot propagate exceptions and therefore cannot participate in transaction propagation. If you want a topic-based bus rather than a type-based one, the docs point at DamiBus instead of stretching EventBus to fit.

Plugin: the same lifecycle, one level up

A Plugin is a module-level participant in the application lifecycle. The interface is three methods:

public interface Plugin {
    void start(AppContext context) throws Throwable;
    default void preStop() throws Throwable {}
    default void stop() throws Throwable {}
}

Plugin start runs after application init completes — before bean scanning, which is exactly why plugins can register interceptors and extensions that the scan will then honor. preStop runs before stop; with safe-stop enabled there is a gap of a few seconds between them. Container start runs after the scan finishes, and container stop runs after plugin stop.

Registration is declarative, close in spirit to Spring Factories or Java SPI. Put the implementation in an integration package, name it XxxSolonPlugin, and keep it free of injection:

package demo.integration;

public class DemoSolonPlugin implements Plugin {
    @Override
    public void start(AppContext context) {
        // plugin starting...
    }

    @Override
    public void preStop() throws Throwable {
    }

    @Override
    public void stop() {
    }
}

Then declare it in a properties file whose name must be globally unique — using the package name is the recommended convention:

META-INF/solon/{packname}.properties

solon.plugin={PluginImpl}
solon.plugin.priority=1

priority is higher-wins, default 0. At startup Solon scans every .properties under META-INF/solon/, collects the plugins, and sorts them.

To drop a plugin that arrived through a transitive dependency, either configure it out:

solon.plugin.exclude:
  - "{PluginImpl}"

or exclude it in code:

Solon.start(App.class, args, app -> {
    app.pluginExclude(PluginImpl.class);
});

Naming tells you where a plugin came from: solon-* is internal architecture, *-solon-plugin is an external adapter, with *-solon-ai-plugin and *-solon-cloud-plugin for the AI and Cloud interface adapters.

The framework's own solon-data is the compact example. Implementation at org.noear.solon.data.integration.DataSolonPlugin:

public class DataSolonPlugin implements Plugin {
    @Override
    public void start(AppContext context) {
        if (Solon.app().enableTransaction()) {
            context.beanInterceptorAdd(Tran.class, new TranInterceptor(), 120);
        }
    }
}

declared in META-INF/solon/solon.data.properties:

solon.plugin=org.noear.solon.data.integration.DataSolonPlugin
solon.plugin.priority=3

That is the entire mechanism behind transaction support: one plugin, registered at a known timing point, adding an interceptor before beans are scanned. Beyond this there are two further layers in the same series — E-SPI for out-of-package extension and H-SPI for hot plug/unplug management — worth knowing exist when you get to modular deployments.

How I decide which hook to use

Working backwards from the failure mode is faster than memorizing the table:

Need injected fields available? Not the constructor. Use @Init.
Need to start a listener or scheduled task? postStart().
Need to deregister before shutdown drains? preStop().
Need to release local resources? @Destroy / stop().
Need something to run when everything is up, including beans created during startup? AppLoadEndEvent.
Need to react before the bean scan? Manual subscription in the Solon.start lambda.
Need to ship the behavior as a reusable module across projects? A Plugin plus one properties file.

The ordering rule is the part I would keep in muscle memory: dependencies define order, and if you need order without a dependency, injection is the cheapest way to declare it.

Docs: https://solon.noear.org/article/240 (lifecycle), https://solon.noear.org/article/480 (LifecycleBean), https://solon.noear.org/article/264 (EventBus), https://solon.noear.org/article/58 (Plugin SPI). Version basis: Solon v4.0.4.

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.