Migration guide

Documentation Index

Fetch the complete documentation index at: https://docs.activeviam.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Migrate to 6.0.0

​

Choose your migration path

​

Headline changes

• Java 21: Java 17 is no longer supported. The Maven build enforces requireJavaVersion 21.
• Atoti Server 6.1.19: Upgraded from ActivePivot 6.0.9. All com.qfs.* and com.quartetfs.* package roots move to com.activeviam.{activepivot,tech,database,web}.*.
• Spring Boot 3 / Jakarta EE 10: javax.* replaced by jakarta.* across the board.
• Spring Security 6: WebSecurityConfigurerAdapter removed; replaced by SecurityFilterChain beans.
• OpenTelemetry 1.43.0: Spring Cloud Sleuth and Zipkin Brave removed.
• Module restructuring: 5 modules become 8. cvarc-application is the new executable; cvarc-starter becomes an auto-config library. See Module rename.
• What-If 2.1.6-AS6.0 → 5.0.0-AS6.1: Hibernate-based persistence, JWT authentication, new file-upload distributed mode. See What-If 2.1.6-AS6.0 → 5.0.0-AS6.1.
• Atoti Server 6.1.19: New Spring Boot starters replace hand-wired configuration. See Atoti Server 6.1.19 starters.
• Atoti Limits 4.2.1: GroupId and artifact ID changed; disabled by default. See Atoti Limits 4.2.1.
• Common Accelerator Library 2.1.15-AS6.1.

​

Path A — no customization

​

Step 1: install JDK 21

# verify before building
java -version          # must report 21.x
mvn -version           # "Java version" must be 21.x
export JAVA_HOME=/path/to/jdk-21

​

Step 2: replace the source tree

​

Step 3: rebuild

mvn clean install

cvarc-application/target/cvarc-application-6.0.0-SNAPSHOT-exec.jar

​

Step 4a: update your launch command — direct jar

java \
  -Dactiveviam.chunkAllocatorClass=com.qfs.chunk.direct.allocator.impl.MmapDirectChunkAllocator \
  --add-opens java.base/java.util.concurrent=ALL-UNNAMED \
  -jar cvarc-starter/target/cvarc-starter-5.1.3-exec.jar \
  --content-service.db.url='jdbc:h2:file:./content_service;DB_CLOSE_DELAY=-1' \
  --contentServer.factory-reset=folder \
  --contentServer.factory-reset.folder-name=file:./bookmarks

java \
  -Xms1024m -Xmx2048m -Xss5m \
  -Dactiveviam.chunkAllocatorKey=mmap \
  --add-opens=java.base/java.util.concurrent=ALL-UNNAMED \
  --add-opens=java.base/java.util=ALL-UNNAMED \
  -jar cvarc-application/target/cvarc-application-6.0.0-SNAPSHOT-exec.jar \
  --contentServer.factory-reset=folder \
  --contentServer.factory-reset.folder-name=file:./bookmarks \
  --csv.topic.path=./data-samples/data

• Jar path and name change to cvarc-application/target/cvarc-application-6.0.0-SNAPSHOT-exec.jar.
• chunkAllocatorClass=…MmapDirectChunkAllocator → chunkAllocatorKey=mmap.
• --add-opens=java.base/java.util=ALL-UNNAMED is a new required flag.
• --content-service.db.url=… is no longer needed — now configured in application.yml.
• --csv.topic.path is new, pointing the Data Load Controller at the CSV samples directory.
• Spring Boot context path moves from /cvarc-starter to /cvarc-application. Update any client or proxy pointing at the old path.

​

Step 4b: update your launch command — Docker

# pre-copy the data the Dockerfile expects
cp -r cvarc-application-tests/src/test/resources/data-samples cvarc-application/src/test/resources/
cp -r bookmarks cvarc-application/src/main/resources/

# build and run
docker build -t cvarc:6.0.0 cvarc-application/
docker run --rm -p 9090:9090 cvarc:6.0.0

​

Step 5: update external file references

​

Path B — light customization (single @Configuration)

• The custom file is a single @Configuration class with @Bean methods, wired by exactly one @Import(...) line on 5.1.3’s ApplicationConfig.
• It does not extend, subclass, or override any of the configs deleted from cvarc-common or cvarc-starter — including all *Tracing* (BraveTracingConfig, TracingConfig, TracingRestServiceConfig), *Monitoring* and ActiveMonitor* (JmxMonitoringConfig, MonitoringRestServicesConfig, ApplicationMonitoringConfig, ActiveMonitorSupportConfig), *CsvSourceConfig, DataLoadControllerConfig, DatastoreConfig, LimitsIntegration, JwtAuthenticationConfigurer, CorsConfig, WhatIfConfig (cvarc-common), WhatIfRestServices, CVARCWhatIfSecurityManager, DoctorPivotConfig, CVAI18nConfig, and I18nConfig. See Step 5 for the full list with replacement guidance.
• It does not customize util.ReferenceLevelUtils (deleted with no upstream replacement). Other ReferenceLevel* types moved upstream to com.activeviam.accelerator.common.{context,postprocessor}.* — Path A still applies if you’re comfortable doing the import rename.
• JDK 21 runtime is acceptable.

​

Step 1: check out the 6.0.0 tree — do not forward-port

• The parent POM jumps from common-parent-pom 1.2.0 to 2.5.0, which retunes the entire dependency graph (Tomcat 9 → 11, slf4j 1.7 → 2.0, logback 1.2 → 1.5, Jakarta servlet API).
• The module list reshapes: cvarc-common splits into cvarc-common-lib + cvarc-common-config; cvarc-ba-activepivot → cvarc-ba-config; cvarc-sa-activepivot → cvarc-sa-config; cvarc-starter is demoted from executable to auto-config library; the new cvarc-application module owns the executable plus the main ApplicationConfig. Replaying these renames over a 5.1.3 checkout is more work than dropping one file into the new tree.
• The @Import graph is now centered on cvarc-application/.../cfg/ApplicationConfig.java with about 25 entries (down from ~50 in 5.1.3), because the deleted configs are now provided transitively by the Atoti Spring Boot starters. The entry point moved from CVAWebApplication (@Configuration @EnableAutoConfiguration @EnableWebMvc, hand-rolling several DispatcherServlet/Filter/ServletContextInitializer beans) to CVARCApplication (@SpringBootApplication @EnableWebMvc; those beans are gone).

​

Step 2: move the custom file

​

Step 3: re-wire the import

@Import(value = {
        ParameterRetrieverConfig.class,
        DatastoreCustomisationsConfig.class,
        SecurityConfig.class,
        // …
        ActivePivotWithDatastoreConfig.class,

        MyCustomConfig.class,        // <-- add this line
})

​

Step 4: fix package and API changes

​

Step 5: remove or replace references to deleted configs

• Tracing — BraveTracingConfig, TracingConfig, TracingRestServiceConfig, brave.Tracing.
• JMX / monitoring — JmxMonitoringConfig, MonitoringRestServicesConfig, ApplicationMonitoringConfig.
• ActiveMonitor — ActiveMonitorSupportConfig, the ActiveMonitor stack (activemonitor-activepivot-impl, repository-activepivot, apm), and activemonitor-support.properties.
• CSV sources — Ba{Aws,Azure,Google,}CsvSourceConfig, Sa{Aws,Azure,Google,}CsvSourceConfig, Shared{Aws,Azure,Google,}CsvSourceConfig, Crif{,Azure}CsvSourceConfig, CommonCloudSourceConfig, and the ACsvSourceConfig family.
• Data load — DataLoadControllerConfig, InitialDataLoadConfig (the first is gone; the second is reshaped under cvarc-starter/.../cfg/impl/dlc/).
• Security — JwtAuthenticationConfigurer and CorsConfig are deleted outright; CORS is now config-driven. All other security classes have relocated from cvarc-starter/.../security/ to cvarc-application/.../security/ with the same class names.
• What-If — WhatIfConfig (cvarc-common copy), WhatIfRestServices. Controllers (StressedSensitivityWhatIfRestController, ParameterSetRestServiceController, TradeRescaleRestServiceController) relocated to cvarc-application/.../whatif/ with the same names.
• Limits — LimitsIntegration. The new limits-auto-config-61 starter is auto-wired but disabled by default; set limits.autoconfiguration.enabled=true if the customization relied on it.
• DoctorPivot — DoctorPivotConfig, doctorpivot-api, doctorpivot-web-app.
• i18n — CVAI18nConfig, I18nConfig, CVARCWhatIfSecurityManager.
• ReferenceLevel context-value chain — IReferenceLevelContextVal, ReferenceLevelContextVal, ReferenceLevelVisualTotalsModeContextVal, ReferenceLevelVisualTotalsModeTranslator, postprocessor.ReferenceLevelLocationShift. Moved upstream to com.activeviam.accelerator.common.{context,postprocessor}.* — see Bucket C for the import rename. util.ReferenceLevelUtils was deleted with no replacement; see Bucket D.

​

Step 6: update the POM (only if the custom file lives in a sibling module)

• Inherit from <artifactId>cvarc</artifactId> <version>6.0.0-SNAPSHOT</version> parent (no version on dependencies; let the parent BOM manage them).
• Add cvarc-common-lib, cvarc-common-config, and cvarc-starter as compile dependencies if the customization needs constants or configs from them.
• Remove these old artifacts if the module POM declares them: com.activeviam.io:data-connectors-{csv,jdbc,aws,azure,gcp}, com.activeviam.activemonitor:*, com.activeviam.apm:apm, com.activeviam.apps:whatif, com.activeviam.apps:cvarc-{ba,sa}-core, org.springframework.cloud:spring-cloud-{starter-sleuth,sleuth-zipkin}, io.zipkin.brave:brave-instrumentation-spring-webmvc, com.activeviam.apps:doctorpivot-{api,web-app}, org.junit:junit-bom, com.activeviam.activepivot:activepivot-test.
• Switch any javax.servlet:javax.servlet-api to jakarta.servlet:jakarta.servlet-api (scope provided).

​

Step 7: update the Dockerfile (only if a custom Dockerfile is maintained)

​

Step 8: build and smoke-test

mvn -DskipTests clean install
java -jar cvarc-application/target/cvarc-application-6.0.0-SNAPSHOT-exec.jar

​

Path C — heavy customization (multi-module edits)

​

Step 0: capture customizations as a patch set

git -C 5.1.3-clean checkout v5.1.3
diff -ruN 5.1.3-clean/ your-5.1.3-checkout/ > customizations.patch

​

Step 1: start from a clean 6.0.0 checkout

git checkout v6.0.0
mvn -version   # must report Java 21

​

Step 2: bucket every customized file

Bucket A — same package path, possibly new module

Bucket B — same code, new home

Bucket C — gone from source; override the upstream bean

Bucket D — redesign against the new API

​

Step 3: run the global find-and-replace for cross-cutting renames

mvn -DskipTests -pl cvarc-common-lib,cvarc-common-config,cvarc-ba-config,cvarc-sa-config,cvarc-starter,cvarc-application compile

​

Step 4: re-wire @Import and the bootstrap class

​

Step 5: POM, Dockerfile, and runtime flags

• Pin nothing. The 6.0.0 parent POM (common-parent-pom:2.5.0) plus common-dependencies-bom:2.5.0 manage versions. Explicit versions in customized POMs cause divergence with the Atoti BOM. If a 5.1.3 customization pinned dataconnectors.version, solutions-tools-bom.version, regression-testing.version, or junit-bom, delete the pin.
• The new cvarc-starter/pom.xml has no spring-boot-maven-plugin repackage execution. The repackage moved to cvarc-application/pom.xml. Customizations that ran the build via cvarc-starter/target/*-exec.jar must repoint at cvarc-application/target/cvarc-application-6.0.0-SNAPSHOT-exec.jar.
• Apply the Hibernate group-ID change (org.hibernate → org.hibernate.orm) in any module POM that pulls Hibernate directly.
• Replace AtotiAuthToken with SharedSecretAuthToken in any custom JGroups protocol XML — see JGroups protocol files.
• Apply the JVM flag changes from Java 21 upgrade and the full Dockerfile diff from Docker configuration. Servlet context-path moves from /cvarc-starter to /cvarc-application.

​

Step 6: data samples and external fixtures

​

Step 7: build, validate, and debug

mvn -DskipTests clean install
java -jar cvarc-application/target/cvarc-application-6.0.0-SNAPSHOT-exec.jar

​

Reference: breaking changes by topic

​

Complete change inventory

​

Module rename

​

Main class rename

// Before (5.1.x)
com.activeviam.cvarc.starter.CVAWebApplication

// After (6.0.x)
com.activeviam.cvarc.application.CVARCApplication

​

Java 21 upgrade

--add-opens=java.base/java.util.concurrent=ALL-UNNAMED
--add-opens=java.base/java.util=ALL-UNNAMED

​

Jakarta EE migration (javax → jakarta)

• javax.servlet.* → jakarta.servlet.*
• javax.persistence.* → jakarta.persistence.*
• javax.validation.* → jakarta.validation.*

// Before (5.1.x)
import javax.servlet.http.HttpServletRequest;
import javax.servlet.ServletContext;

// After (6.0.x)
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.ServletContext;

​

Spring security 6 migration

// Before (5.1.x)
public abstract class AJwtSecurityConfigurer extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .antMatcher(JwtRestServiceConfig.REST_API_URL_PREFIX + "/**")
            .csrf().disable()
            .cors().and()
            .authorizeRequests()
            .antMatchers("/**").hasAnyAuthority(APP_ROLE__USER)
            .and()
            .httpBasic().authenticationEntryPoint(authenticationEntryPoint);
    }
}

// After (6.0.x)
@Bean
@Order(3)
protected SecurityFilterChain jwtSecurityFilterChain(HttpSecurity http, MvcRequestMatcher.Builder mvc) throws Exception {
    return http
        .csrf(AbstractHttpConfigurer::disable)
        .cors(Customizer.withDefaults())
        .securityMatcher(mvc.pattern(url(JwtRestServiceConfig.REST_API_URL_PREFIX + "/**")))
        .authorizeHttpRequests(auth -> auth
            .requestMatchers(mvc.pattern(HttpMethod.OPTIONS, "**")).permitAll()
            .anyRequest().hasAnyAuthority(APP_ROLE__USER))
        .httpBasic(basic -> basic.authenticationEntryPoint(new HttpStatusEntryPoint(HttpStatus.UNAUTHORIZED)))
        .build();
}

@Bean
@Scope("prototype")
MvcRequestMatcher.Builder mvc(HandlerMappingIntrospector introspector) {
    return new MvcRequestMatcher.Builder(introspector);
}

​

OpenTelemetry replaces Spring Sleuth

• opentelemetry-spring-boot-starter
• opentelemetry-sdk-extension-autoconfigure
• opentelemetry-logback-mdc-1.0

otel:
  instrumentation:
    annotations:
      enabled: false

tracing:
  enabled: true

// Before (5.1.x)
@Autowired
brave.Tracing tracing;
// ...
brave.Span span = tracing.tracer().nextSpan();

// After (6.0.x)
var tracer = io.opentelemetry.api.GlobalOpenTelemetry.getTracer("my-instrumentation");
var span = tracer.spanBuilder("my-span").startSpan();

​

DispatcherServlet configuration removal

​

Atoti Server 6.1.19 starters

<dependency>
    <groupId>com.activeviam.springboot</groupId>
    <artifactId>atoti-server-starter</artifactId>
</dependency>
<dependency>
    <groupId>com.activeviam.springboot</groupId>
    <artifactId>atoti-ui-starter</artifactId>
</dependency>
<dependency>
    <groupId>com.activeviam.springboot</groupId>
    <artifactId>atoti-admin-ui-starter</artifactId>
</dependency>

​

Data load controller changes

​

What-If 2.1.6-AS6.0 → 5.0.0-AS6.1

@Bean
public ISimulationPersistenceManager persistenceManager(IDatabaseService databaseService) {
    DatabaseSimulationPersistenceManager persistenceManager = new DatabaseSimulationPersistenceManager();
    persistenceManager.setDatabaseService(databaseService);
    return persistenceManager;
}

@Bean
public ISimulationPersistenceManager persistenceManager(WhatIfHibernateProperties whatIfHibernateProperties) {
    var configuration = new org.hibernate.cfg.Configuration();
    var properties = new Properties();
    properties.putAll(whatIfHibernateProperties.getPersistence());
    configuration.addProperties(properties);
    configuration.addAnnotatedClass(DatabaseSimulationJPA.class);
    var sessionFactory = configuration.buildSessionFactory();

    HibernateSimulationPersistenceManager<DatabaseSimulationJPA> persistenceManager =
            HibernateSimulationPersistenceManager.of(DatabaseSimulationJPA.class);
    persistenceManager.setSessionFactory(sessionFactory);
    return persistenceManager;
}

// Before (2.1.6-AS6.0)
@Bean
public IDatabaseSimulationsSecurityManager securityManager() {
    return new SpringDatabaseSimulationsSecurityManager();
}

// After (5.0.0)
@Bean
public IDatabaseSimulationsSecurityManager securityManager(
        ISimulationPersistenceManager persistenceManager,
        IBranchPermissionsManager branchPermissionsManager) {
    return new SpringDatabaseSimulationsSecurityManager(persistenceManager, branchPermissionsManager);
}

// After (5.0.0)
@Bean
@Profile("WhatIf")
@ConditionalOnMissingBean
public AddressSupplier addressSupplier() {
    return () -> mvPivot.getClusterMembersRestAddresses().values().stream()
            .map(addr -> addr.regionMatches(true, 0, "http", 0, 4) ? addr : ("http://" + addr))
            .collect(Collectors.toSet());
}

@Bean
@Profile("WhatIf")
@ConditionalOnMissingBean
public AuthenticatorSupplier authenticatorSupplier(IJwtService jwtService) {
    return () -> new JwtAuthenticator(jwtService);
}

@Bean
@Primary
@Profile("WhatIf")
public IDatabaseService restRemoteService(AddressSupplier addressSupplier, AuthenticatorSupplier authenticatorSupplier) {
    return new RestDistributedDatabaseService(addressSupplier, authenticatorSupplier);
}

• CVARCWhatIfSecurityManager: superseded by SpringDatabaseSimulationsSecurityManager.
• TradeScaleDTO: superseded by TradeRescaleDTO.
• TradeDuplicateAndRescaleSimulationDefinition: replaced by TradeDuplicateSimulationDefinition and TradeScalingSimulationDefinition.
• WhatIfConfig (from cvarc-common) and WhatIfRestServices: replaced by WhatIfConfig in cvarc-application.
• StressedSensitivitySimulationDefinition, StressedSensitivityWhatIfException, StressedSensitivityWhatIfSubmitter: replaced by FileUploadSimulationDefinition and FileUploadWhatIfSubmitter.
• AddressSupplier, AuthenticatorSupplier: superseded by Spring 6 HTTP Service Proxy configuration in RestClientConfig.

• Exception package: What-If REST exceptions (including CVAServiceException) are now under com.activeviam.tools.whatif.rest. Update any exception imports in custom code.
• IDistributedQueryResultsMerger: the interface no longer exposes branch-deletion or fast-forward methods. Remove any custom overrides of those methods; they are handled internally by the new distributed What-If pipeline.
• Lombok annotation processor: several base classes in atoti-what-if-lib now use Lombok. Custom code extending them must declare org.projectlombok:lombok on the annotation processor classpath, otherwise compilation fails on missing constructors and accessors.

​

Atoti Limits 4.2.1

​

Hibernate upgrade

<!-- Before (5.1.x) -->
<dependency>
    <groupId>org.hibernate</groupId>
    <artifactId>hibernate-c3p0</artifactId>
</dependency>

<!-- After (6.0.x) -->
<dependency>
    <groupId>org.hibernate.orm</groupId>
    <artifactId>hibernate-c3p0</artifactId>
</dependency>

​

JGroups protocol files

<!-- Before (5.1.x) -->
<AUTH auth_class="com.activeviam.activepivot.dist.impl.internal.distribution.security.impl.AtotiAuthToken"
      auth_token.auth_value="distribution_password"
      auth_token.token_hash="SHA"/>

<!-- After (6.0.x) -->
<AUTH auth_class="com.activeviam.common.distribution.security.SharedSecretAuthToken"
      auth_token.auth_value="distribution_password"
      auth_token.token_hash="SHA"/>

​

Configuration files (cvarc.properties, application.yml)

​

Docker configuration

​

Migration checklist

1. Install JDK 21 and confirm java -version reports 21.x.
2. Confirm JAVA_HOME points at the JDK 21 installation.

3. Replace the 5.1.3 source tree with the 6.0.0 tree (clean checkout — do not forward-merge).
4. Update Maven <artifactId> references using the module rename table.
5. Replace CVAWebApplication with CVARCApplication in IDE run configurations, Docker images, and deployment scripts.
6. If Spring-context tests are in a fork, move them to cvarc-application-tests.

7. Replace all javax.* imports with jakarta.* (servlet, persistence, validation).
8. Apply the full find-and-replace regex table from Path C step 3.
9. Rename CVARCEnvConstants constants from _SYSPROP/_SYNSPROP/_PROP to _PROPERTY.
10. Rename the six SAMeasureBuilder SENSITITIVIES constants to SENSITIVITIES.
11. Rename ReferenceLevelTranslator.KEY to ReferenceLevelTranslator.TRANSLATOR_KEY.

12. Remove references to BraveTracingConfig, TracingConfig, TracingRestServiceConfig, and brave.Tracing.
13. Remove references to JmxMonitoringConfig, MonitoringRestServicesConfig, ApplicationMonitoringConfig.
14. Remove references to ActiveMonitorSupportConfig, the ActiveMonitor stack, and activemonitor-support.properties.
15. Remove references to all Ba/Sa/Shared/Crif*CsvSourceConfig classes and CommonCloudSourceConfig.
16. Remove references to LimitsIntegration; if Limits was active, set limits.autoconfiguration.enabled=true.
17. Remove references to DoctorPivotConfig, doctorpivot-{api,web-app}.
18. Remove JwtAuthenticationConfigurer and CorsConfig; CORS is now config-driven.
19. Remove dispatcherServletRegistration bean overrides — see DispatcherServlet configuration removal.

20. Migrate from WebSecurityConfigurerAdapter to SecurityFilterChain beans.
21. Add the MvcRequestMatcher.Builder bean.
22. Configure AuthenticationManager as a bean.

23. Replace com.activeviam.apps:whatif with atoti-what-if-lib and add atoti-what-if-spring-boot-starter.
24. Migrate persistenceManager bean to HibernateSimulationPersistenceManager.
25. Update securityManager bean to inject ISimulationPersistenceManager and IBranchPermissionsManager.
26. Update any RestDistributedDatabaseService wiring from UserAuthenticator to JwtAuthenticator.
27. Update REST clients calling /services/rest/what-if/ to /activeviam/what-if/rest/v3.
28. Update exception imports to com.activeviam.tools.whatif.rest.
29. Remove overrides of deleted IDistributedQueryResultsMerger branch-deletion and fast-forward methods.
30. Update imports for TradeRescaleRestServiceController (moved to cvarc-application).
31. Remove references to CVARCWhatIfSecurityManager, TradeScaleDTO, and TradeDuplicateAndRescaleSimulationDefinition.
32. Update REST clients that check the response body for failure status to handle HTTP error codes instead.
33. Ensure Lombok is on the annotation processor classpath if custom code extends affected What-If classes.

34. Remove deprecated cvarc.properties entries listed in the configuration files section.
35. Review logback.xml for compatibility with Logback 1.5.x.

36. Replace AtotiAuthToken with SharedSecretAuthToken in all JGroups protocol XML files.

37. Update the jar path from cvarc-starter/target/… to cvarc-application/target/cvarc-application-6.0.0-SNAPSHOT-exec.jar.
38. Replace -Dactiveviam.chunkAllocatorClass=…MmapDirectChunkAllocator with -Dactiveviam.chunkAllocatorKey=mmap.
39. Add --add-opens=java.base/java.util=ALL-UNNAMED to JVM flags.
40. Drop --content-service.db.url=… from the launch line.
41. Add --csv.topic.path=./data-samples/data if using the bundled CSV samples.
42. Update any reverse proxy or client that references the old /cvarc-starter context path.
43. Update Docker base image to eclipse-temurin:21.
44. Move the Docker build context from cvarc-starter/ to cvarc-application/; pre-copy data-samples and bookmarks before building.

45. Run mvn -DskipTests clean install from the project root.
46. Start the application and verify it reaches the ready state.
47. Verify all security filter chains and What-If simulation flows work correctly.