SOFAArk Class Isolation and Hot Deployment for Java Applications

Why SOFAArk Targets Dependency Conflicts That Version Management Cannot Resolve

SOFAArk addresses a specific Java packaging problem: an application may need two incompatible versions of the same dependency. The README gives the case of library A requiring version 0.1 of library C while library B requires version 0.2, with both versions unable to coexist. Unified dependency management can select one version, but that does not satisfy both callers at runtime. The resulting classpath can produce errors such as `LinkageError` and `NoSuchMethodError`.

The project separates incompatible code with different ClassLoaders. For this dependency conflict, the documented approach is to package library A and version 0.1 of C together as an `Ark Plugin`, then let the application depend on that Plugin. This is useful when two consumers genuinely require incompatible library versions, not when an application merely needs closer control over normal transitive dependency resolution.

SOFAArk is not limited to Spring Boot or SOFABoot applications. The README describes it as a general Java framework that can integrate with other development frameworks. Its likely users are server-side Java teams managing several versions of shared libraries, or teams combining independently developed applications whose dependency graphs cannot be reconciled into one classpath. It is a poor fit when there is no isolation requirement and ordinary Maven dependency management already produces a consistent runtime.

How SOFAArk Divides Containers, Plugins, and Biz Modules

The runtime is organized around three package types: `Ark Container`, `Ark Plugin`, and `Ark Biz`. The container is the runtime manager. It starts first, discovers Plugins and Biz modules on the classpath, reads their configuration, builds class-loading indexes, loads each component with an independent ClassLoader, and starts components according to their configured priority.

An `Ark Plugin` contains one or more ordinary Java dependencies in the required Ark package layout. Its configuration describes which classes are imported or exported and includes its startup priority. Plugins use a `PluginClassLoader`. The documented relationship is deliberately different for Plugins and Biz modules: Plugins have bidirectional class indexes, so one Plugin can delegate class loading to another Plugin. A Biz can index classes exposed by Plugins, but Plugins cannot reverse that dependency and load arbitrary classes from the Biz.

An `Ark Biz` represents an application module and the dependencies and configuration needed to start it. Each Biz is loaded through its own `BizClassLoader`, which is what allows multiple applications in one JVM to retain separate dependency graphs. Plugins load before Biz modules. This model creates controlled sharing rather than merging every dependency into one unrestricted classpath.

An Ark package is an executable Fat Jar built in a required directory layout. It commonly contains the container, Plugins, and Biz modules. The launch path remains a normal Java process, but the container performs discovery and classloader management after startup.

Static and Dynamic Combined Deployment in One JVM

SOFAArk uses its isolation model for two deployment forms. Static combined deployment packages dependent Biz modules into one Ark package. Teams can develop modules independently and define interfaces between them instead of negotiating one shared dependency stack. The README names `SofaService/SofaReference` JVM services as the interaction mechanism between applications. Because every application has a separate `BizClassLoader`, one module can use a dependency version that conflicts with another module's choice.

Dynamic combined deployment moves module installation and uninstallation to runtime. The documented control paths are a client API and a Config Plugin connected to Zookeeper. The client API lets a host application control deployable Biz modules. The Config Plugin parses configuration received from Zookeeper and uses it to control module deployment and removal. The README does not provide those client calls, endpoint settings, Zookeeper keys, or authentication details, so this page cannot supply a working dynamic deployment example without inventing configuration.

Every combined deployment has a master application. If the Ark package contains one Biz, that Biz is the default master. With several Biz modules, the package must specify the master. The master is not unloadable and is commonly the traffic entry point, while replaceable implementations remain in dynamic Biz modules. This restriction gives the runtime a stable host but also means the architecture is not fully symmetric.

Building and Launching the First SOFAArk Package

The README does not publish a complete standalone installation recipe with Maven coordinates, plugin configuration, or a sample `pom.xml`. It directs new users to two quick-start guides: one for isolating a class conflict with multiple Ark Plugins and one for building an Ark Plugin from an ordinary Maven application. The build plugins named by the project are `sofa-ark-plugin-maven-plugin` for Plugins and `sofa-ark-maven-plugin` for Ark packages and Biz modules.

A practical first pass is therefore to open the ordinary Maven Plugin guide, configure the project with the documented Plugin layout, package the dependency pair that conflicts with the rest of the application, and inspect the resulting Fat Jar. The README confirms that this Plugin can contain one or more normal Java JARs plus its import, export, and priority configuration.

After an Ark package has been produced, the only launch command documented in the README is shown below. Replace the illustrative filename with the actual package filename in a real project.

java -jar application.jar

The container should start before it discovers and loads the included Plugins and Biz modules. The README states that Plugins load before Biz modules and that each component starts according to its configured priority. It does not define the expected console output, so verification should focus on the package layout and module lifecycle rather than assume a particular log sequence.

Operational Boundaries of Class Isolation and Hot Deployment

Class isolation does not make incompatible code interchangeable. Teams must decide which classes a Plugin exports, which classes it imports, and which direction each dependency may use. Incorrect indexes can cause missing classes or load a type from an unintended ClassLoader. The one-way rule between Plugins and Biz modules is particularly important: a Biz may consume Plugin-provided classes, but a Plugin cannot treat the Biz as an ordinary dependency source.

The dynamic model also introduces lifecycle responsibility. The master cannot be unloaded, while deployable Biz modules can be installed or removed through an API or the Zookeeper-backed Config Plugin. The README does not cover rollback, failed installation behavior, in-flight request draining, state migration, compatibility between module versions, or recovery after a configuration failure. These omissions matter when assessing whether the framework can support a production control plane.

The project is also the wrong tool for a small application whose dependencies form one stable graph. Adding Plugins, Biz packages, import and export rules, service contracts, and lifecycle configuration creates more packaging and diagnostic work than plain dependency management. The host cannot disappear during module replacement, so applications that require every component to start and stop together are a poor match for the documented master and dynamic Biz design.

SOFAArk Versus OSGi, Unified Dependencies, and Koupleless

The README positions SOFAArk against OSGi. OSGi is described as a capable isolation framework whose feature set and implementation are considered heavier for the project's common dependency-conflict use case. SOFAArk instead focuses on a smaller Ark Container, Plugins, Biz modules, executable Fat Jar packaging, and deployment APIs. The exact footprint or feature comparison is not quantified in the README, but the architectural difference is explicit.

Compared with Spring Boot-style dependency management, SOFAArk does not require all consumers to accept one version of every conflicting library. Each Biz or Plugin can retain its own class-loading context. The cost is an explicit isolation policy and inter-module API contract rather than a single unified dependency tree.

Koupleless is related but not presented as an interchangeable implementation. The README says it is a modular application development framework and platform built from SOFAArk's dynamic combined deployment ideas. It organizes applications around a base and independently deployed modules, with further concerns such as resources and environment abstraction. A team looking specifically for `Ark Container`, `Ark Plugin`, `Ark Biz`, and the SOFAArk packaging model should examine SOFAArk itself. A team seeking the broader modular application platform described in the README should also review Koupleless.

SOFAArk Release Coverage, Maintenance, and Apache-2.0 Use

The repository is not archived, and its last push was on 2026-10-05. The listed v3.2.1 and v3.2.0 releases were published on 2026-07-14 and name JDK 17, JDK 21, and JDK 25 support. The earlier v3.1.11 release was published on 2025-08-07 and names JDK 17 and JDK 21. These facts indicate recent repository activity and explicit coverage for newer JDK releases, but they do not establish compatibility for JDK versions absent from the release descriptions.

SOFAArk uses the Apache-2.0 license. The repository includes `LICENSE`, `CONTRIBUTING.md`, and a `SOFAArk2.0` migration guide link for upgrades from version 1.0 to 2.0. The documentation provided here does not describe compatibility from 2.x to the current 3.x line, dependency changes, configuration migration steps, or a general upgrade procedure. License obligations and permitted use therefore need to be evaluated from the Apache-2.0 text and project notices rather than inferred from the release list.

Before upgrading, the most concrete checks are the target JDK, Maven plugin configuration, Ark package directory layout, Plugin import and export indexes, master application selection, and any Config Plugin connection used for dynamic deployment. Those artifacts sit directly on the runtime path described by the README.

Editorial conclusion

Teams running incompatible dependency versions, or independently developed applications that must share one JVM, should evaluate SOFAArk after checking its class-loading policy and deployment model. Applications with a stable unified dependency graph and little need for runtime module changes are better served by a conventional Fat Jar. The first concrete verification is to package one isolated Plugin or Biz and confirm that its imports, exports, service bindings, and lifecycle behavior match the intended module boundary.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. sofastack/sofa-ark on GitHub