Apache Commons Library Migration in IBM Content Navigator

Affected Versions

The following versions of IBM Content Navigator have been updated:

• IBM Content Navigator 3.2.0 IF002
• IBM Content Navigator 3.1.0 IF008
• IBM Content Navigator 3.0.15 IF009

What Has Changed

Library Migrations

The following Apache Commons libraries have been migrated to their newer, actively maintained versions:

Specific Package Changes

Commons Configuration:

• Old: org.apache.commons.configuration.*
• New: org.apache.commons.configuration2.*

Commons Lang:

• Old: org.apache.commons.lang.*
• New: org.apache.commons.lang3.*

Why This Change Was Necessary

The legacy Commons Configuration and Commons Lang libraries are no longer actively maintained and contain known security vulnerabilities with published CVE reports. To maintain security compliance and protect customer environments, IBM has updated to the current, supported versions of these libraries.

Key reasons for migration:

• Security: Address critical and high-severity CVEs in legacy libraries
• Support: Transition to actively maintained library versions
• Compatibility: Align with current Apache Commons project standards
• Long-term viability: Ensure continued security updates and bug fixes

Potential Impact on Custom Plugins

Symptoms of Incompatibility

Custom plugins developed against earlier versions of IBM Content Navigator may experience the following issues after upgrading to one of the affected versions:

1. Compilation Errors
   • ClassNotFoundException or NoClassDefFoundError during build
   • Import statements cannot be resolved
   • Missing package errors
2. Runtime Errors
   • Plugin fails to load in Content Navigator
   • ClassNotFoundException at runtime
   • NoSuchMethodError if method signatures have changed
   • Plugin initialization failures
3. Behavioral Changes
   • Configuration parsing may behave differently in Commons Configuration2
   • Some deprecated methods may no longer be available

Affected Plugin Code

Your plugin is likely affected if it contains imports such as:

import org.apache.commons.configuration.*;
import org.apache.commons.lang.*;

Resolution Steps

Step 1: Update Import Statements

Replace legacy import statements with their new equivalents:

Commons Configuration:

// Old
import org.apache.commons.configuration.Configuration;
import org.apache.commons.configuration.XMLConfiguration;
import org.apache.commons.configuration.ConfigurationException
...

// New
import org.apache.commons.configuration2.Configuration;
import org.apache.commons.configuration2.XMLConfiguration;
import org.apache.commons.configuration2.ex.ConfigurationException
...

Commons Lang:

// Old
import org.apache.commons.lang.StringUtils;
import org.apache.commons.lang.ArrayUtils;
...

// New
import org.apache.commons.lang3.StringUtils;
import org.apache.commons.lang3.ArrayUtils;
...

Step 2: Update Maven Dependencies

If your plugin uses build management tools, update your dependency declarations:

Maven (pom.xml):

<!-- Remove old dependencies -->
<!-- 
<dependency>
   <groupId>commons-configuration</groupId>
   <artifactId>commons-configuration</artifactId>
</dependency>
<dependency>
   <groupId>commons-lang</groupId>
   <artifactId>commons-lang</artifactId>
</dependency>
-->

<!-- Add new dependencies -->
<dependency>
   <groupId>org.apache.commons</groupId>
   <artifactId>commons-configuration2</artifactId>
   <version>2.12.0</version>
   <scope>provided</scope>
</dependency>
<dependency>
   <groupId>org.apache.commons</groupId>
   <artifactId>commons-lang3</artifactId>
   <version>3.18.0</version>
   <scope>provided</scope>
</dependency>

Step 3: Review API Changes

While many APIs remain similar, some notable changes in Commons Configuration2.

Consult the Apache Commons Configuration2 and Lang3 migration guides for comprehensive API changes:

• Commons Configuration2 Migration Guide
• Commons Lang3 Migration Notes

Step 4: Important Note on Dependencies

If your project includes commons-configuration2, you must also include commons-beanutils in your dependency management. 

This is because commons-beanutils is a required transient dependency of commons-configuration2 that may not be included automatically by all build tools.

For a complete list of required libraries, please refer to the official Commons Configuration Runtime Dependencies documentation.

Step 5: Rebuild and Test

1. Clean your build environment
2. Rebuild your plugin with the updated dependencies
3. Deploy to a test Content Navigator environment
4. Thoroughly test all plugin functionality
5. Review logs for any runtime warnings or errors

Backward Compatibility Considerations

Important: Plugins updated for the affected IBM Content Navigator versions will NOT be compatible with earlier versions of Content Navigator that still use the legacy Commons libraries.

If you need to maintain compatibility with multiple Content Navigator versions:

1. Option A: Maintain separate plugin branches/versions for different Content Navigator releases
2. Option B: Use reflection and conditional logic to detect available libraries at runtime (advanced, not recommended)
3. Option C: Recommend that customers upgrade to one of the affected or later Content Navigator versions

Testing Recommendations

Before deploying updated plugins to production:

1. Unit Testing: Verify all configuration and utility functions work as expected
2. Integration Testing: Test plugin initialization and loading in Content Navigator
3. Functional Testing: Validate all plugin features in the Navigator UI
4. Performance Testing: Ensure no performance degradation
5. Security Scanning: Run vulnerability scans on updated plugin dependencies

Additional Resources

• Apache Commons Configuration2 Documentation
• Apache Commons Lang3 Documentation
• IBM Content Navigator Plugin Development Guide
• Affected IBM Content Navigator version Release Notes

Support

If you encounter issues migrating your custom plugins:

1. Review the Apache Commons migration documentation linked above
2. Check the IBM Content Navigator support forums
3. Contact IBM Support with your plugin compilation or runtime errors
4. Include relevant stack traces, build logs, and plugin code samples

Summary Checklist

• Identify all custom plugins using Commons Configuration or Commons Lang
• Update import statements from org.apache.commons.lang.* to org.apache.commons.lang3.*
• Update import statements from org.apache.commons.configuration.* to org.apache.commons.configuration2.*
• Update build dependencies (Maven)
• Review and update API usage for Commons Configuration2 changes
• Rebuild plugins against the affected version of IBM Content Navigator
• Test thoroughly in a non-production environment
• Plan deployment schedule for updated plugins
• Update plugin documentation with new version requirements