In-process runtime governance for the JVM

Keep long-running
JVM systems evolving
one module at a time.

No teardown of the legacy system, and no application restart for every change.
With the business module as the unit, loading, canary, call governance and reclamation
close the loop inside a single JVM.

v0.4.7 · HanzhangPre-1.02026.09.26
Business JARs load and unload independentlyProgressive traffic shift across versionsObservable reclamation results
A long-running JVM

Host application / LingCore

Shared API: loaded contracts stay frozen

Call governance

Routing · Rate limiting · Bulkhead · Permissions · Audit

Ling v1 85%

Baseline version

Ling v2 15%

Canary version

Pre-check → Drain → UnloadObserve ClassLoader reclamation
Isolated ClassLoaders. The 85% / 15% split is an example traffic weight, not live runtime data.
Default Spring Boot 2.7 / JDK 8Spring Boot 3.5 / JDK 17 supportedApache-2.0 open source
01 / Definition and positioning

Govern what happens inside the process,
so every change is easier to control.

External platforms manage what lies between services. LingFrame manages what lies inside the JVM.
The two work together; you don’t have to pick one.

LingFrame (灵珑) is an open-source (Apache-2.0) in-process runtime governance framework for the JVM: with independent business JARs (Lings) as the boundary, long-running JVM systems can load and unload modules, run multiple versions under weighted canary, and keep evolving through unified call governance and observable reclamation, without tearing down the legacy system or restarting the application for every change.

Ling · 灵元

A business JAR that can be loaded, run, governed and unloaded independently.

An independent ClassLoader isolates private dependencies, and the Ling talks to its host through explicit contracts. Spring Boot business modules are supported, as are Native Java modules that don’t start a Spring container.

A business boundary, not just a code directory.

Between processes

K8s / Gateway / Service Mesh

Deployment scheduling, network routing, capacity scaling and instance-level rolling updates.

Inside the process

LingFrame

Module load/unload, weighted canary, call governance, lifecycle and reclamation observation.

02 / Evolution path

Coexist first, then ramp up.
Retire the old version only after verification.

Break one wholesale replacement into steps you can observe and adjust.
Ramp up with traffic weights; retire in order with lifecycle management.

01

Coexist

Keep the baseline implementation and load the new version independently.

v1 + v2
02

Canary

Start with a small share and route requests by weight.

weighted routing
03

Observe

Check calls, exceptions and runtime signals.

observe & decide
04

Drain

Stop assigning new traffic and wait for in-flight requests to finish.

awaitIdle
05

Unload

Complete resource cleanup, then observe reclamation.

unload → observe

If the canary misbehaves, take back the traffic weight first. Actual ClassLoader reclamation still depends on reference release and the JVM GC.

03 / Where it fits

Split with boundaries.
Evolve with a way back.

Suited to JVM applications that must run for a long time yet keep changing in parts.

Legacy monolith, gradual split

Keep the stable entry point and default implementation. Let new business modules run on their own first, then take over traffic step by step.

Start from one module with a clear boundary

Extend capabilities, iterate independently

Release rules, connectors or business extensions on their own schedule, rather than tying them to the release cadence of the whole application.

Spring Boot / Native Java

Long-lived processes, careful reclamation

Care not only about “can it load”, but also about in-flight requests, resource references and ClassLoader reclamation results at exit.

Make exit part of the lifecycle too
04 / Public verification

Loading is not enough.
Verify that it can exit.

Test scope, observed results and open questions, side by side.
Look at the public evidence first, then judge whether it fits your workload.

SeaTunnel Agent · v0.3.1

After GC, no target loaders remained in this test.

0

Target Job ClassLoaders remaining

Live target loaders after GC in this test; not a result for all runtime scenarios.

Read the release PR and test results
Leftover target Job ClassLoadersCOUNT
Agent group0
Control group567
15Scenario coverage

Expanded from 14 to 15, adding MongoDB → Hive

12E2E passed

End-to-end test results from the release PR report

Final Metaspace90.47 MiB

90.47 MiB is the final usage, not the growth.

Long-term Metaspace convergence still needs verification. One successful reclamation does not mean there is no leak under any workload.

Historical report kept separate, not mixed with this test’s metrics

The earlier 144 interleaved jobs, 96.3% class unload rate and 14.06 MB Metaspace increase belong to a different set of experiments. They are not the current test metrics, and they do not mean 144 jobs ran concurrently.

View the historical verification report
Migration / RuoYi

See the adoption path in a migration example.

The RuoYi example repository shows an engineering path from an existing monolith to Ling boundaries. It is a reference implementation, not a promise of “zero changes” for any business.

View the RuoYi migration example
Historical microbenchmark / JMH

Micro-benchmarks are a reference; real workloads still need load testing.

July 9 empty-business JMH averages: governance only ≈0.8 µs; with terminal invocation ≈19 µs. Not p95 or v0.4.7 results; test your workload.

View the benchmark module and reproduction notes
05 / Start evaluating

Get one module running first.
Then evaluate the next step.

Get familiar with load/unload and governance using the official example, then verify your own business.
The default environment is JDK 8 + Spring Boot 2.7, and Maven is required.

  1. 1

    Get the project

    Clone the repository and enter the project directory.

  2. 2

    Build and start

    Run the example LingCore and watch Ling loading and routing.

  3. 3

    Verify real business

    With real dependencies, threads and data sources, check module load/unload and resource release.

Read the full quick start
Run the official example
# 01  Get the project
git clone https://github.com/LingFrame/LingFrame.git
cd LingFrame

# 02  Build the example LingCore
mvn -pl lingframe-examples/lingframe-example-lingcore-app -am package -DskipTests

# 03  Start
cd lingframe-examples/lingframe-example-lingcore-app
mvn spring-boot:run
After startup, open http://localhost:8888/dashboard.html
What is LingFrame?

LingFrame is an open-source (Apache-2.0) in-process runtime governance framework for the JVM, built for JVM applications that must run for a long time yet keep changing in parts. With independent business JARs (Lings) as the boundary, it closes the loop of module load/unload, multi-version canary, call governance and observable reclamation inside a single JVM.

How does LingFrame relate to microservices and K8s? Is it a replacement?

No, it is not a replacement. The two work together, and you don’t have to pick one. K8s, gateways and service meshes manage what lies between processes: deployment scheduling, network routing, capacity scaling and instance-level rolling updates. LingFrame manages what lies inside the process: module load/unload, weighted canary, call governance, lifecycle and reclamation observation. LingFrame does not handle cross-process network communication, cluster scheduling or node disaster recovery.

What are a Ling and LingCore?

A Ling is a business JAR that can be loaded, run, governed and unloaded independently. It isolates private dependencies with its own ClassLoader and talks to its host through explicit contracts. LingCore is the host application that carries Lings.

Which JDK and Spring Boot versions does LingFrame support?

The default environment is Spring Boot 2.7 with JDK 8, and Spring Boot 3.5 with JDK 17 is also supported. Maven is required to build. A Ling can be a Spring Boot business module, or a Native Java module that does not start a Spring container.

What is the fastest way to try LingFrame?

The fastest way is to run the official example: clone the repository, build and start the example LingCore, then open http://localhost:8888/dashboard.html to watch Ling loading and routing. You can also open the live demo dashboard at dashboard.lingframe.cn first (public demo token: lingframe) to get familiar with the operations; before adopting, you still need to verify your own business locally.

How much overhead does LingFrame add?

July 9 empty-business JMH averages: governance only ≈0.8 µs; with terminal invocation ≈19 µs. Not p95 or v0.4.7 results; test your workload.

Can it be used in production now?

v0.4.7 is still Pre-1.0. Validate real business workloads, dependencies and resource release in a test environment first, then check authentication, configuration and observability against the production hardening checklist.

Can the Shared API be hot-updated together with a Ling?

No. Contracts already loaded into the shared boundary do not support hot update or hot unload, in order to keep types consistent across ClassLoaders. You can preload a new contract package; breaking changes to existing contracts still require a process restart.

Does a finished unload mean memory drops immediately?

No. The unload flow stops routing, drains requests, closes the context and releases references; actual reclamation of the ClassLoader and class metadata also depends on leftover references and the JVM GC. Verify with observation rather than the unload status alone.

Are all JDBC calls covered by data source governance?

No. Managed data source governance mainly covers the DataSource injected through Spring; raw JDBC connections created by hand are not within the same interception boundary. Verify resource ownership and transaction propagation against the documentation.

Is the Dashboard required?

No. The Dashboard is an optional module that must be enabled explicitly. You can also manage things through configuration or Actuator. When authentication is enabled in production, configure a dedicated access token instead of reusing the public demo token.