[
https://issues.apache.org/jira/browse/UNOMI-876?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18008997#comment-18008997
]
Serge Huber commented on UNOMI-876:
-----------------------------------
h1. Karaf Upgrade Report
h2. Overview
This report outlines the required steps to upgrade the Unomi application from
Apache Karaf {color:red}4.2.15{color} to {color:green}4.4.7{color}. This major
upgrade is necessary to incorporate new features, security patches, and
performance improvements. The upgrade requires a move from Java 11 to Java 17
and involves significant updates to several key dependencies.
h2. Dependency Version Changes
The following table summarizes the version changes for the core frameworks and
libraries involved in this upgrade. These versions have been verified by
inspecting the binary distributions of both Karaf versions.
|| Framework/Library || Current Version (in Karaf 4.2.15) || Target Version (in
Karaf 4.4.7) ||
| Java | 11 | {color:green}17{color} |
| Apache Karaf | 4.2.15 | {color:green}4.4.7{color} |
| Apache Camel | 2.23.1 | {color:green}4.9.0{color} |
| Apache CXF | 3.3.2 | {color:green}3.6.5{color} (Latest compatible) |
| Pax Web | 7.2.29 | {color:green}8.0.30{color} |
| Aries Blueprint Core| 1.10.3 | {color:green}1.10.3{color} (No change) |
| Jackson | 2.13.5 | {color:green}~2.15.x{color} (or latest compatible) |
| OSGi Core | 6.0.0 | {color:green}8.0.0{color} |
| Servlet API | 3.1.0 | {color:green}4.0.1{color} |
*Notes on Target Versions:*
* *Apache CXF*: *Critical Decision* - CXF 4.0.0 removes OSGi support entirely,
making it incompatible with Karaf and Unomi. Therefore, we must target the
latest *CXF 3.6.5* version, which maintains OSGi support while providing Java
17 compatibility.
* *Servlet API*: The move from 3.1.0 to 4.0.1 *does not* require the
{code}javax.servlet{code} to {code}jakarta.servlet{code} namespace migration.
This remains in the {code}javax{code} namespace.
h2. Major Breaking Changes and Upgrade Requirements
h3. Java Version Requirement
* *Current*: Java 11
* *Required*: Java 17
* *Impact*: All code must be compatible with Java 17
* *Tasks*:
** Update build configuration to require Java 17
** Review and update any Java 11-specific code
** Update CI/CD pipelines to use Java 17
h3. Apache Camel Upgrade (2.23.1 to 4.9.0)
This is the most significant upgrade in terms of breaking changes. The jump
spans two major versions (3.x and 4.x).
*Breaking Changes:*
* Package structure changes
* API changes in core components
* Removal of deprecated features
* Component modularization
*Tasks:*
* Update Camel dependencies in {code}unomi/extensions/router/pom.xml{code}
* Review and update Camel route configurations
* Test all Camel integrations
* Remove OGNL usage as it's not compatible with Java 17
h3. Apache CXF Upgrade (3.3.2 to 3.6.5)
*Impact*: Moderate version upgrade within the same major version
*Tasks:*
* Update CXF dependencies in all REST modules
* Review and update JAX-RS annotations
* Test all REST endpoints
* Update CXF features in Karaf configuration
h3. Pax Web (7.2.29 to 8.0.30)
*Tasks:*
* Update Pax Web dependencies
* Review and update web container configurations
* Test web applications and servlets
h3. Jackson Dependencies
*Current*: Multiple versions in use
*Required*: Update to latest compatible versions
*Tasks:*
* Standardize Jackson versions across modules
* Update Jackson annotations and configurations
* Test JSON serialization/deserialization
h3. OSGi and Servlet API
*Impact*: Version updates required
*Tasks:*
* Update OSGi dependencies
* Update Servlet API dependencies
* Review and update bundle manifests
h2. Code Impact Analysis and Required Changes
Based on an analysis of the source code, the following areas will be
significantly impacted by the upgrade. The required changes are detailed below.
h3. Servlet API Upgrade (3.1.0 to 4.0.1)
The upgrade to Servlet API 4.0.1, as provided by Pax Web 8.0.30 in Karaf 4.4.7,
*does not require the {code}javax.servlet{code} to {code}jakarta.servlet{code}
package migration.* The {code}javax.servlet{code} namespace is maintained in
this version.
*Impact:*
* *No package renaming required:* All existing {code}import
javax.servlet.*{code} statements will remain valid.
* *High backward compatibility:* Servlet 4.0 is largely backward compatible
with 3.0. Most existing code will run without modification.
* *New Features Available:* The main addition in Servlet 4.0 is support for
HTTP/2 features, including the {code}PushBuilder{code} API. These are optional
and don't affect existing code.
*Areas to Verify:*
* *Custom Servlet Classes:* Any classes extending {code}HttpServlet{code} or
implementing servlet interfaces should be tested to ensure they work correctly
with the new API.
* *GraphQL Servlet:* The custom {code}GraphQLServlet{code} in
{code}unomi/graphql/cxs-impl/src/main/java/org/apache/unomi/graphql/servlet/GraphQLServlet.java{code}
should be tested thoroughly. It extends {code}WebSocketServlet{code} and has
complex security and CORS handling.
h3. OGNL Removal (Validation: Correct Strategy)
*Current Situation:* OGNL is already disabled by default in the current
codebase. The {code}org.apache.unomi.security.properties.useOGNLScripting{code}
system property defaults to {code}false{code}, and the
{code}PropertyConditionEvaluator.init(){code} method logs "OGNL Script
disabled".
*Validated Plan:*
* *Remove OGNL Code:* Since OGNL is already disabled and poses security risks,
the entire OGNL code path can be safely removed from
{code}PropertyConditionEvaluator.java{code}.
* *Promote Groovy Actions:* Users who need complex, dynamic logic should be
directed to use the existing {code}groovy-actions{code} extension, which is
more secure and maintainable.
*Code Example for Removal:*
In
{code}unomi/plugins/baseplugin/src/main/java/org/apache/unomi/plugins/baseplugin/conditions/PropertyConditionEvaluator.java{code}:
{code:java}
// Remove this entire method and related OGNL code:
private Object getOGNLPropertyValue(Item item, String expression) throws
OgnlException {
Object target = item;
return Ognl.getValue(Ognl.parseExpression(expression), target);
}
// Simplify the getPropertyValue method to only use the simple property access
{code}
h3. Apache Camel Upgrade (2.23.1 to 4.9.0) - Critical Migration
This is the most complex part of the upgrade, involving two major version jumps.
*Validated Code Impact:*
The router extension in {code}unomi/extensions/router{code} uses the following
Camel components (verified by codebase analysis):
* {code}camel-servlet{code} (for HTTP endpoints)
* {code}camel-ftp{code} (for FTP endpoints)
* {code}camel-kafka{code} (for Kafka integration)
* {code}camel-http-common{code} (for HTTP utilities)
*Required Changes:*
*a) Dependency Modularization:*
The {code}camel-core{code} artifact was split into many smaller JARs in Camel
3.x. Update {code}unomi/extensions/router/pom.xml{code}:
{code:xml}
<!-- Replace single camel-core dependency with modular ones -->
<dependency>
<groupId>org.apache.camel</groupId>
<artifactId>camel-core</artifactId>
<version>${camel.version}</version>
</dependency>
<dependency>
<groupId>org.apache.camel</groupId>
<artifactId>camel-bean</artifactId>
<version>${camel.version}</version>
</dependency>
<dependency>
<groupId>org.apache.camel</groupId>
<artifactId>camel-direct</artifactId>
<version>${camel.version}</version>
</dependency>
<!-- Add other specific components as needed -->
{code}
*b) Component Name Changes:*
Based on migration guides, these components were renamed:
* {code}http4{code} → {code}http{code} (verify if used)
* {code}http4s{code} → {code}https{code} (verify if used)
*c) API Changes:*
* {code}CamelContext.start(){code} behavior may have changed
* Route builder APIs may have been updated
* Error handling mechanisms may have changed
h3. Apache CXF Upgrade (3.3.2 to 3.6.5) - Validated
The decision to target the latest *CXF 3.6.5* version is validated as correct,
as it maintains OSGi support and avoids the {code}javax{code} to
{code}jakarta{code} namespace migration that would be required by CXF 4.0.
*Code Impact Validation:*
* *{code}RestServer.java{code}:* A review of this class confirms it is the
central point for REST configuration. The upgrade to 3.6.x is unlikely to cause
major breakages, as the core {code}JAXRSServerFactoryBean{code} and related
APIs are stable within the 3.x series. However, the custom providers and
interceptors listed below are the primary areas of risk and must be thoroughly
tested:
** {code}AuthenticationFilter{code}
** {code}SecurityFilter{code}
** {code}AuthorizingInterceptor{code}
** {code}RequestValidatorInterceptor{code}
* *No {code}ClaimsAuthorizingFilter{code}:* A search of the codebase confirms
that Unomi does not use {code}ClaimsAuthorizingFilter{code}, so the package
name change mentioned in some CXF migration guides is not a concern.
* *Blueprint Configuration:* The blueprint files that configure CXF endpoints
should be reviewed, but major changes are not expected within the 3.x series.
h3. Blueprint XML Files
*Affected Files (Complete List):*
All Blueprint XML files will need to be reviewed for compatibility:
{code}
unomi/lifecycle-watcher/src/main/resources/OSGI-INF/blueprint/blueprint.xml
unomi/metrics/src/main/resources/OSGI-INF/blueprint/blueprint.xml
unomi/rest/src/main/resources/OSGI-INF/blueprint/blueprint.xml
unomi/scripting/src/main/resources/OSGI-INF/blueprint/blueprint.xml
unomi/services/src/main/resources/OSGI-INF/blueprint/blueprint.xml
unomi/wab/src/main/resources/OSGI-INF/blueprint/blueprint.xml
unomi/extensions/geonames/rest/src/main/resources/OSGI-INF/blueprint/blueprint.xml
unomi/extensions/geonames/services/src/main/resources/OSGI-INF/blueprint/blueprint.xml
unomi/extensions/groovy-actions/rest/src/main/resources/OSGI-INF/blueprint/blueprint.xml
unomi/extensions/groovy-actions/services/src/main/resources/OSGI-INF/blueprint/blueprint.xml
unomi/extensions/json-schema/rest/src/main/resources/OSGI-INF/blueprint/blueprint.xml
unomi/extensions/json-schema/services/src/main/resources/OSGI-INF/blueprint/blueprint.xml
unomi/extensions/lists-extension/actions/src/main/resources/OSGI-INF/blueprint/blueprint.xml
unomi/extensions/lists-extension/rest/src/main/resources/OSGI-INF/blueprint/blueprint.xml
unomi/extensions/lists-extension/services/src/main/resources/OSGI-INF/blueprint/blueprint.xml
unomi/extensions/privacy-extension/rest/src/main/resources/OSGI-INF/blueprint/blueprint.xml
unomi/extensions/privacy-extension/services/src/main/resources/OSGI-INF/blueprint/blueprint.xml
unomi/extensions/router/router-rest/src/main/resources/OSGI-INF/blueprint/blueprint.xml
unomi/extensions/router/router-service/src/main/resources/OSGI-INF/blueprint/blueprint.xml
unomi/extensions/salesforce-connector/actions/src/main/resources/OSGI-INF/blueprint/blueprint.xml
unomi/extensions/salesforce-connector/rest/src/main/resources/OSGI-INF/blueprint/blueprint.xml
unomi/extensions/salesforce-connector/services/src/main/resources/OSGI-INF/blueprint/blueprint.xml
{code}
h3. Karaf Feature Files
*Affected Files (Complete List):*
All feature XML files will need version updates:
{code}
unomi/kar/src/main/feature/feature.xml
unomi/extensions/router/router-karaf-feature/src/main/feature/feature.xml
unomi/extensions/groovy-actions/karaf-kar/src/main/feature/feature.xml
unomi/extensions/salesforce-connector/karaf-kar/src/main/feature/feature.xml
unomi/extensions/weather-update/karaf-kar/src/main/feature/feature.xml
unomi/graphql/karaf-feature/src/main/feature/feature.xml
unomi/samples/graphql-providers-feature/src/main/feature/feature.xml
{code}
h2. Detailed Upgrade Verification and Implementation Plan
h3. Current State Analysis
*Verified Current Configuration:*
* *Java Version*: Currently set to Java 11 in {code}unomi/pom.xml{code} (line
85: {code}<java.version>11</java.version>{code})
* *Karaf Version*: 4.2.15 (multiple locations in pom.xml files)
* *Camel Version*: 2.23.1 (in {code}unomi/extensions/router/pom.xml{code})
* *CXF Version*: 3.3.11 (in {code}unomi/pom.xml{code})
* *Pax Web*: 3.1.0 (in {code}unomi/pom.xml{code})
* *OSGi Core*: 6.0.0 (in {code}unomi/pom.xml{code})
* *Servlet API*: 3.0.1 (in {code}unomi/pom.xml{code})
*Critical Findings:*
# OGNL Usage: Confirmed that OGNL is already disabled by default
({code}useOGNLScripting{code} defaults to {code}false{code})
# Camel Router: Extensive use of Camel 2.23.1 in the router extension with
complex route configurations
# Blueprint XML: Multiple blueprint files that will need review for
compatibility
# Java Version Mismatch: Package configuration still references Java 1.8
({code}<javase>1.8</javase>{code}) in {code}unomi/package/pom.xml{code}
h4. Java Client Library Version Requirements
*Current Java Client Versions in Unomi:*
* *Elasticsearch*: 7.4.2 (using
{code}elasticsearch-rest-high-level-client{code})
* *OpenSearch*: 2.18.0 (using {code}opensearch-java{code} client)
*Java Version Requirements for Upgraded Clients:*
h5. Elasticsearch 9.x Java Client
* *Minimum Java Version*: *Java 17*
* *Recommended Java Version*: *Java 17 or 21*
* *Client Library*: {code}elasticsearch-java{code} (new Java API client)
* *Key Changes*:
** New Java API client provides better type safety and modern Java features
** *Requires Java 17+* (as specified in the official build.gradle.kts)
** Replaces the deprecated high-level REST client
** Forward compatible with Elasticsearch versions
** *Note*: The new {code}elasticsearch-java{code} client requires Java 17+
(does not support Java 8 or 11)
h5. OpenSearch 3.x Java Client
* *Minimum Java Version*: *Java 8*
* *Recommended Java Version*: *Java 11, 17, or 21*
* *Client Library*: {code}opensearch-java{code}
* *Key Changes*:
** Enhanced security features and improved performance
** Better integration with modern Java ecosystem
** *Compatibility Matrix*:
*** Client Version 1.0.0: JDK 8
*** Client Version 2.x.0: JDK 8 / 11 / 17 / 21
*** Client Version 3.x.0: JDK 8 / 11 / 17 / 21
*Impact on Unomi Upgrade:*
# *Java Version Requirements*:
** OpenSearch 3.x Java client supports Java 8, 11, 17, and 21
** Elasticsearch 9.x Java client requires Java 17+ (as per official
build.gradle.kts)
** Both current clients (Elasticsearch 7.4.2 and OpenSearch 2.18.0) are
compatible with Java 17
# *ASLv2 Licensing Constraints*:
** {code}elasticsearch-rest-high-level-client{code} above 7.4.2: Cannot be used
due to license incompatibility with ASLv2
** {code}elasticsearch-java{code} client: ASLv2 compatible, can be used for
newer Elasticsearch server versions
** OpenSearch client: Fully compatible with ASLv2 license requirements
** Server connections: REST API connections don't have transitive licensing
issues
# *Client Migration Strategy*:
** Elasticsearch Path: Migrate from high-level client to
{code}elasticsearch-java{code} client (ASLv2 + Java 17 compatible)
** OpenSearch Path: Continue using OpenSearch client (ASLv2 compatible,
supports Java 17+)
** Server Versions: Can connect to Elasticsearch 8.x/9.x servers using
ASLv2-compatible {code}elasticsearch-java{code} client
# *Compatibility*: Java 17 (required for Karaf 4.4.7) is compatible with all
viable search engine clients
*Recommended Approach:*
# Java 17 Migration: Update all Java version references to 17
# Dependency Updates: Update core dependencies to target versions
# Camel Migration: Migrate router extension from Camel 2.23.1 to 4.9.0
# Search Engine Client Migration: Migrate to compatible Java clients
# Testing: Comprehensive testing of all components
h4. Apache Software License v2 (ASLv2) Compatibility Requirements
*Critical Licensing Constraint:*
Apache Unomi, as an Apache Software Foundation project, *only accepts libraries
that are compatible with the Apache Software License v2 (ASLv2)*.
*Elasticsearch Client Library Licensing Issues:*
* {code}elasticsearch-rest-high-level-client{code} versions above 7.4.2: *NOT
compatible with ASLv2*
* {code}elasticsearch-java{code} client: *ASLv2 compatible* (new Java API
client)
* Current Unomi Version: Uses Elasticsearch 7.4.2 with high-level client (ASLv2
compatible)
* Server Connection: REST API connection to Elasticsearch server doesn't have
transitive licensing issues
*Impact on Elasticsearch Client Upgrade Path:*
# Cannot upgrade {code}elasticsearch-rest-high-level-client{code} above 7.4.2
due to licensing incompatibility
# Can use {code}elasticsearch-java{code} client (ASLv2 compatible) for newer
Elasticsearch server versions
# OpenSearch client remains fully viable as it uses ASLv2 license
*Recommended Search Engine Strategy:*
* Elasticsearch Path: Migrate from
{code}elasticsearch-rest-high-level-client{code} to
{code}elasticsearch-java{code} client (ASLv2 compatible)
* OpenSearch Path: Continue using OpenSearch client (ASLv2 compatible)
* Server Versions: Can connect to Elasticsearch 8.x/9.x servers using the
ASLv2-compatible {code}elasticsearch-java{code} client
*Code Migration Examples:*
*Elasticsearch Java API Client (New):*
{code:java}
// New Elasticsearch 9.x code using elasticsearch-java client
ElasticsearchClient client = new ElasticsearchClient(
transport, new JacksonJsonpMapper()
);
SearchResponse<JsonData> response = client.search(s -> s
.index("index")
.query(q -> q.matchAll(m -> m)), JsonData.class);
{code}
*OpenSearch Client (Current and Future):*
{code:java}
// Current OpenSearch 2.18.0 code (compatible with Java 17)
OpenSearchClient client = new OpenSearchClient(transport);
SearchResponse<JsonData> response = client.search(s -> s
.index("index")
.query(q -> q.matchAll(m -> m)), JsonData.class);
{code}
h3. Detailed Upgrade Steps
h4. Step 1: Update Java Version Configuration
*Files to Update:*
# {code}unomi/pom.xml{code} - Update Java version from 11 to 17
# {code}unomi/package/pom.xml{code} - Update javase from 1.8 to 17
*Required Changes:*
{code:xml}
<!-- In unomi/pom.xml -->
<properties>
<java.version>17</java.version>
<maven.compiler.source>${java.version}</maven.compiler.source>
<maven.compiler.target>${java.version}</maven.compiler.target>
</properties>
<!-- In unomi/package/pom.xml -->
<javase>17</javase>
{code}
h4. Step 2: Update Core Dependencies
*Files to Update:*
# {code}unomi/pom.xml{code} - Update all version properties
# All extension pom.xml files - Update dependency versions
*Required Changes:*
{code:xml}
<!-- In unomi/pom.xml -->
<properties>
<karaf.version>4.4.7</karaf.version>
<cxf.version>3.6.5</cxf.version>
<version.jackson.core>2.15.4</version.jackson.core>
<version.jackson.databind>2.15.4</version.jackson.databind>
<version.jackson.jaxb>2.15.4</version.jackson.jaxb>
<version.karaf>4.4.7</version.karaf>
<version.pax.exam>4.13.5</version.pax.exam>
<!-- Update OSGi versions -->
<osgi.core.version>8.0.0</osgi.core.version>
<osgi.cmpn.version>8.0.0</osgi.cmpn.version>
<!-- Update Servlet API -->
<servlet.api.version>4.0.1</servlet.api.version>
<!-- Update Pax Web -->
<pax.web.version>8.0.30</pax.web.version>
</properties>
{code}
h4. Step 3: Update Camel Router Extension
*Files to Update:*
# {code}unomi/extensions/router/pom.xml{code} - Update Camel version and
dependencies
# All Camel route builder classes - Review for API compatibility
*Required Changes:*
{code:xml}
<!-- In unomi/extensions/router/pom.xml -->
<properties>
<camel.version>4.9.0</camel.version>
<kafka.client.version>3.6.1</kafka.client.version>
<commons-net.version>3.10.0</commons-net.version>
</properties>
<!-- Add modular Camel dependencies -->
<dependencies>
<dependency>
<groupId>org.apache.camel</groupId>
<artifactId>camel-core</artifactId>
<version>${camel.version}</version>
</dependency>
<dependency>
<groupId>org.apache.camel</groupId>
<artifactId>camel-bean</artifactId>
<version>${camel.version}</version>
</dependency>
<dependency>
<groupId>org.apache.camel</groupId>
<artifactId>camel-direct</artifactId>
<version>${camel.version}</version>
</dependency>
<dependency>
<groupId>org.apache.camel</groupId>
<artifactId>camel-servlet</artifactId>
<version>${camel.version}</version>
</dependency>
<dependency>
<groupId>org.apache.camel</groupId>
<artifactId>camel-ftp</artifactId>
<version>${camel.version}</version>
</dependency>
<dependency>
<groupId>org.apache.camel</groupId>
<artifactId>camel-kafka</artifactId>
<version>${camel.version}</version>
</dependency>
<dependency>
<groupId>org.apache.camel</groupId>
<artifactId>camel-jackson</artifactId>
<version>${camel.version}</version>
</dependency>
<dependency>
<groupId>org.apache.camel</groupId>
<artifactId>camel-http-common</artifactId>
<version>${camel.version}</version>
</dependency>
</dependencies>
{code}
*Camel Route Builder Changes Required:*
# {code}RouterCamelContext.java{code}: Update imports and API usage
# Route Builder Classes: Review for deprecated methods and API changes
# Kafka Configuration: Update Kafka component configuration for newer versions
h4. Step 4: Remove OGNL Code
*Files to Update:*
#
{code}unomi/plugins/baseplugin/src/main/java/org/apache/unomi/plugins/baseplugin/conditions/PropertyConditionEvaluator.java{code}
*Required Changes:*
{code:java}
// Remove OGNL imports
// import ognl.*;
// import ognl.enhance.ExpressionAccessor;
// Remove OGNL-related fields
// private final Map<String, Map<String, ExpressionAccessor>> expressionCache =
new HashMap<>(64);
// private static final ClassLoader secureFilteringClassLoader = new
SecureFilteringClassLoader(PropertyConditionEvaluator.class.getClassLoader());
// private final boolean useOGNLScripting =
Boolean.parseBoolean(System.getProperty("org.apache.unomi.security.properties.useOGNLScripting",
"false"));
// Simplify getPropertyValue method
protected Object getPropertyValue(Item item, String expression) throws
Exception {
if (usePropertyConditionOptimizations) {
Object result = getHardcodedPropertyValue(item, expression);
if
(!HardcodedPropertyAccessor.PROPERTY_NOT_FOUND_MARKER.equals(result)) {
return result;
}
}
// OGNL code removed - return null for unsupported expressions
return null;
}
// Remove all OGNL-related methods:
// - getOGNLPropertyValue()
// - getOgnlContext()
// - getPropertyAccessor()
// - ClassLoaderClassResolver inner class
{code}
h4. Step 5: Update Blueprint XML Files
*Key Areas to Review:*
# CXF Configuration: Update CXF endpoint configurations
# OSGi Service References: Verify service interface compatibility
# Bean Definitions: Update any deprecated bean configurations
*Example Updates:*
{code:xml}
<!-- Update CXF version references -->
<bean id="cxf" class="org.apache.cxf.bus.spring.SpringBus">
<property name="properties">
<map>
<entry key="cxf.version" value="3.6.5"/>
</map>
</property>
</bean>
<!-- Update OSGi service references if needed -->
<reference id="someService"
interface="org.apache.unomi.api.services.SomeService"/>
{code}
h4. Step 6: Update Karaf Feature Files
*Files to Update:*
# All feature XML files in the project
*Required Changes:*
{code:xml}
<!-- Update feature versions -->
<feature name="unomi-router" version="2.7.0-SNAPSHOT">
<!-- Update bundle versions -->
<bundle>mvn:org.apache.camel/camel-core/4.9.0</bundle>
<bundle>mvn:org.apache.camel/camel-servlet/4.9.0</bundle>
<!-- ... other bundles -->
</feature>
{code}
h4. Step 7: Update Test Dependencies
*Files to Update:*
# All test pom.xml files
# Test classes that may use deprecated APIs
*Required Changes:*
{code:xml}
<!-- Update test dependencies -->
<dependency>
<groupId>org.ops4j.pax.exam</groupId>
<artifactId>pax-exam-container-karaf</artifactId>
<version>4.13.5</version>
<scope>test</scope>
</dependency>
{code}
h3. Testing Strategy
h4. Phase 1: Unit Testing
# Camel Route Tests: Test all route builders with new Camel version
# Property Condition Tests: Verify OGNL removal doesn't break functionality
# CXF REST Tests: Test all REST endpoints with new CXF version
# Blueprint Tests: Verify all blueprint configurations work
h4. Phase 2: Integration Testing
# Router Integration: Test complete import/export workflows
# REST API Testing: Test all REST endpoints
# Servlet Testing: Test web applications and servlets
# OSGi Bundle Testing: Verify all bundles start correctly
h4. Phase 3: End-to-End Testing
# Full Application Startup: Test complete application startup
# Feature Installation: Test all Karaf features
# Performance Testing: Verify no performance regressions
# Security Testing: Verify security features still work
h3. Rollback Plan
*Rollback Strategy:*
# Git Branches: Maintain separate branches for upgrade work
# Dependency Snapshots: Keep snapshots of working dependency versions
# Configuration Backups: Backup all configuration files
# Test Data: Maintain test data sets for validation
*Rollback Triggers:*
# Critical functionality failures
# Performance degradation > 20%
# Security vulnerabilities
# Incompatibility with required integrations
h2. Time and Effort Estimation
The following table provides a detailed breakdown of the estimated time
required for each major task in the upgrade. The estimates assume the use of
AI-powered tools for code analysis and generation, which can significantly
reduce the time required for routine tasks.
|| Task Category || Specific Task || Estimated Time || AI Tool Benefit || Notes
||
| Planning & Analysis | Detailed code analysis and planning | 1-2 days | High |
AI can help analyze dependencies and identify breaking changes |
| Environment Setup | Java 17 setup, IDE configuration | 0.5 days | Medium |
Straightforward but needs testing |
| Dependency Updates | Update all pom.xml files with new versions | 1-2 days |
High | AI can help identify and update dependencies systematically |
| OGNL Removal | Remove OGNL code from PropertyConditionEvaluator | 0.5 days |
High | Clear, isolated change that AI can help with |
| Camel Migration | Update Camel routes and dependencies | 3-5 days | Medium |
Most complex part, requires careful testing |
| CXF Updates | Update REST configurations and test | 1-2 days | Medium |
Mostly configuration changes |
| Blueprint XML | Review and update all Blueprint files | 1-2 days | High | AI
can help identify necessary changes |
| Feature Files | Update Karaf feature definitions | 1 day | High | Systematic
version updates |
| Testing Phase | Comprehensive testing of all functionality | 3-5 days | Low |
Requires manual verification |
| Documentation | Update documentation and migration notes | 1 day | High | AI
can help generate documentation |
| Contingency | Buffer for unexpected issues | 2-3 days | N/A | Always plan for
unknowns |
*Total Estimated Time: 14-25 days*
*Key Points:*
* The Camel route migration and the integration testing are the largest and
most complex tasks.
* AI tools can significantly reduce the time for dependency updates, code
analysis, and documentation.
* The actual time may vary depending on the complexity of the existing Camel
routes and the extent of custom modifications.
* *Thoroughly test all integrations and functionalities* after the upgrade to
identify and fix any issues.
h2. Risk Assessment and Mitigation
h3. High-Risk Areas
# Camel Route Migration: Complex route configurations may have compatibility
issues
** Mitigation: Extensive testing of all routes, gradual migration approach
# Performance Impact: New versions may introduce performance changes
** Mitigation: Performance benchmarking before and after upgrade
# Third-Party Integration: External systems may have compatibility issues
** Mitigation: Test all integrations thoroughly, maintain backward
compatibility where possible
h3. Medium-Risk Areas
# Blueprint Configuration: OSGi service references may need updates
** Mitigation: Systematic review of all blueprint files
# Custom Extensions: Third-party extensions may not be compatible
** Mitigation: Test all extensions, update or replace incompatible ones
h3. Low-Risk Areas
# Servlet API: High backward compatibility expected
# Jackson: Well-established upgrade path
# OSGi Core: Standard version upgrade
h2. Success Criteria
The upgrade will be considered successful when:
# All Tests Pass: 100% of unit and integration tests pass
# Performance Maintained: No more than 5% performance degradation
# All Features Work: All existing functionality works as expected
# Security Validated: All security features still function correctly
# Documentation Updated: All documentation reflects new versions
# Deployment Successful: Application deploys and starts without issues
h2. Post-Upgrade Tasks
# Monitoring: Monitor application performance and stability
# Documentation: Update all technical documentation
# Training: Train team on new features and changes
# Optimization: Identify and implement performance optimizations
# Security Review: Conduct security review of new versions
> Ugrade to the latest stable version of Karaf
> --------------------------------------------
>
> Key: UNOMI-876
> URL: https://issues.apache.org/jira/browse/UNOMI-876
> Project: Apache Unomi
> Issue Type: Sub-task
> Reporter: Serge Huber
> Assignee: Jonathan Sinovassin-Naïk
> Priority: Major
>
> h1. Upgrade to Karaf 4.4.7 and Related Dependencies
> h2. Overview
> Upgrade Apache Karaf to version 4.4.7 and update related dependencies to
> ensure compatibility. This upgrade brings significant changes including Java
> 17 requirement and major version updates to key components.
> h2. Current Dependencies
> Apache Karaf: Current version (based on codebase)
> Apache Camel: 2.23.1
> Apache CXF: Current version
> Pax Web: 3.1.0
> Aries Blueprint: Current version
> Jackson: Various versions
> OSGi Core: 6.0.0
> Servlet API: 3.0.1
> h2. Breaking Changes and Required Updates
> h3. 1. Java Version Requirement
> Current: Java 11
> Required: Java 17
> Impact: All code must be compatible with Java 17
> Tasks:
> Update build configuration to require Java 17
> Review and update any Java 11-specific code
> Update CI/CD pipelines to use Java 17
> h3. 2. Apache Camel Upgrade
> Current: 2.23.1
> Required: 4.9.0 (comes with Karaf 4.4.7)
> Breaking Changes:
> Package structure changes
> API changes in core components
> Removal of deprecated features
> * Tasks:
> Update Camel dependencies in
> {code:java}
> unomi/extensions/router/pom.xml{code}
> Review and update Camel route configurations
> Test all Camel integrations
> Remove OGNL usage as it's not compatible with Java 17
> h3. 3. Apache CXF
> Impact: Major version upgrade
> Tasks:
> Update CXF dependencies in all REST modules
> Review and update JAX-RS annotations
> Test all REST endpoints
> Update CXF features in Karaf configuration
> h3. 4. Pax Web
> Current: 3.1.0
> Required: Update to latest compatible version
> Tasks:
> Update Pax Web dependencies
> Review and update web container configurations
> Test web applications and servlets
> h3. 5. Aries Blueprint
> Impact: Version upgrade required
> Tasks:
> Update Blueprint dependencies
> Review and update Blueprint XML configurations
> Test Blueprint container functionality
> h3. 6. Jackson Dependencies
> Current: Multiple versions in use
> Required: Update to latest compatible versions
> Tasks:
> Standardize Jackson versions across modules
> Update Jackson annotations and configurations
> Test JSON serialization/deserialization
> h3. 7. OSGi and Servlet API
> Impact: Version updates required
> Tasks:
> Update OSGi dependencies
> Update Servlet API dependencies
> Review and update bundle manifests
> h2. Code Changes Required
> h3. 1. Router Extension
> {code:xml}
> <!-- Update in unomi/extensions/router/pom.xml -->
> <properties>
> <camel.version>4.9.0</camel.version>
> <!-- Update other versions -->
> </properties>
> {code}
> h3. 2. REST Modules
> Update CXF dependencies in all REST modules
> Review and update JAX-RS annotations
> Test all REST endpoints
> h3. 3. Blueprint Configurations
> Review and update Blueprint XML files in:
> {code:java}
> unomi/metrics/src/main/resources/OSGI-INF/blueprint/{code}
> {code:java}
> unomi/wab/src/main/resources/OSGI-INF/blueprint/{code}
> {code:java}
> unomi/services/src/main/resources/OSGI-INF/blueprint/{code}
> h3. 4. Karaf Features
> Update feature definitions in:
> {code:java}
> unomi/kar/src/main/feature/feature.xml{code}
> {code:java}
> unomi/extensions/router/router-karaf-feature/src/main/feature/feature.xml{code}
> h2. Testing Requirements
> h3. 1. Unit Tests
> Update test dependencies
> Fix any broken tests
> Add new tests for Java 17 compatibility
> h3. 2. Integration Tests
> Update Pax Exam configuration
> Test all OSGi bundles
> Test all REST endpoints
> Test Camel routes
> Test Blueprint configurations
> h3. 3. Performance Testing
> Benchmark critical paths
> Memory usage analysis
> Startup time analysis
> h2. Migration Steps
> Create a new branch for the upgrade
> Update parent POM with new versions
> Update all module POMs
> Update code for Java 17 compatibility
> Update configurations
> Run and fix tests
> Perform integration testing
> Document changes
> Create upgrade guide
> h2. Risks and Mitigations
> h3. 1. Risk: Breaking changes in Camel 4.x
> Mitigation: Thorough testing of all Camel routes
> Mitigation: Create migration guide for Camel changes
> h3. 2. Risk: Java 17 compatibility issues
> Mitigation: Early testing with Java 17
> Mitigation: Code review focusing on Java 17 compatibility
> h3. 3. Risk: OSGi bundle compatibility
> Mitigation: Test all bundles individually
> Mitigation: Review bundle manifests
> h3. 4. Risk: Performance regression
> Mitigation: Performance testing before/after
> Mitigation: Monitoring during deployment
> h2. Dependencies
> Karaf 4.4.7
> Camel 4.9.0
> Latest compatible versions of:
> Apache CXF
> Pax Web
> Aries Blueprint
> Jackson
> OSGi Core
> Servlet API
> h2. Notes
> Backup all configurations before upgrade
> Document all breaking changes
> Update CI/CD pipelines for Java 17
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
