Inoyu OSGi Utilities Maven Plugin

The Inoyu OSGi Utilities Maven Plugin is a collection of utilities designed to help developers work with OSGi bundles in Maven projects. This plugin provides several goals to analyze, validate, and manage OSGi-related aspects of your project.

Features

• Package Analysis: Locate packages within project dependencies and analyze package usage in OSGi bundles
• Manifest Management: View and validate OSGi bundle manifests with enhanced formatting
• Blueprint to DS Conversion: Automatically convert OSGi Blueprint XML files to Declarative Services annotations
• Blueprint Validation: Validate Blueprint XML files for syntax and semantic correctness
• Theme Support: Dark and light theme support for better readability

Prerequisites

• Maven 3.8.5 or later
• Java 8 or later

Usage

This plugin can be used directly from the command line. Some goals require a Maven project context, while others can be used both within a project and independently.

Locate Packages

This goal must be run within a Maven project context:

mvn dev.inoyu:osgi-utils-maven-plugin:1.3:locate-package -Dpackage=com.example.package1

This goal scans your project's dependencies and reports where the specified package is found.

Sample Output:

📦 Package found in Project classes
Dependency trail:
├─ dev.inoyu:osgi-tools:1.1
com/example/package1/Class1.class
com/example/package1/Class2.class

Analyze Package Usage

This goal must also be run within a Maven project context:

mvn dev.inoyu:osgi-utils-maven-plugin:1.3:find-package-usages -Dpackage=com.example.package

This goal examines your project and its dependencies to find where the specified packages are used.

Sample Output:

Searching for usages of package: com.example.package
📦 Usage found in Dependency: org.example:example-artifact:1.0: com/example/usage/Class1 uses com.example.package.Class2
Dependency trail:
├─ org.example:example-artifact:1.0

View Manifest

This goal can be used both within a Maven project context and independently:

1. Within a Maven project:

   mvn dev.inoyu:osgi-utils-maven-plugin:1.3:view-manifest

   This will display the manifest of the project's main artifact.

2. For arbitrary JAR files (can be used anywhere):

   mvn dev.inoyu:osgi-utils-maven-plugin:1.3:view-manifest -Djars=path/to/your/jar1.jar,path/to/your/jar2.jar

This goal displays the contents of the OSGi bundle manifest, including all headers and their values with enhanced formatting.

Sample Output:

Analyzing manifest of: path/to/your/jar1.jar
================================================================================
Bundle-Name: Example Bundle
Bundle-SymbolicName: com.example.bundle
Bundle-Version: 1.0.0
Export-Package: com.example.package;version="1.0.0"
Import-Package: org.osgi.framework;version="[1.3,2)"
================================================================================

Validate Blueprint XML

This goal validates Blueprint XML files for syntax and semantic correctness:

mvn dev.inoyu:osgi-utils-maven-plugin:1.3:validate-blueprint

Configuration Options:

Parameter	Default	Description
blueprint.sourceDir	${project.build.sourceDirectory}	Source directory containing Java classes
blueprint.resourcesDir	${project.build.resources[0].directory}	Resources directory containing Blueprint XML files
blueprint.failOnError	true	Whether to fail the build on validation errors

Sample Output:

🔍 Validating Blueprint XML files...
✅ Blueprint validation completed successfully
📊 Validation Summary:
   - Files processed: 3
   - Errors: 0
   - Warnings: 2

Blueprint to DS Conversion

The convert-blueprint-to-ds goal automatically converts OSGi Blueprint XML files to Declarative Services annotations in Java code.

Features

• Converts Blueprint XML to DS annotations
• Handles all OSGi Blueprint features:
  • Services and references
  • Property placeholders and configurations
  • Reference lists and dynamic references
  • Karaf shell commands
  • Service properties and metadata
  • Init/destroy methods
  • Bundle context injection
• Recursive processing of multi-module projects
• Selective module inclusion/exclusion

Usage

1. Add the plugin to your project's pom.xml:

<build>
    <plugins>
        <plugin>
            <groupId>dev.inoyu</groupId>
            <artifactId>osgi-utils-maven-plugin</artifactId>
            <version>1.3</version>
        </plugin>
    </plugins>
</build>

2. Add required dependencies for DS annotations:

<dependencies>
    <dependency>
        <groupId>org.osgi</groupId>
        <artifactId>org.osgi.service.component.annotations</artifactId>
        <version>1.5.1</version>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>org.osgi</groupId>
        <artifactId>org.osgi.service.metatype.annotations</artifactId>
        <version>1.4.1</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

3. Run the conversion:

mvn osgi-utils:convert-blueprint-to-ds

Configuration Options

Parameter	Default	Description
keepBlueprintFiles	false	Whether to keep the original Blueprint XML files after conversion
recursive	false	Whether to process sub-modules recursively
includeModules	null	Array of module name patterns to include (regex)
excludeModules	null	Array of module name patterns to exclude (regex)

Advanced Usage Examples

Process only specific modules:

mvn osgi-utils:convert-blueprint-to-ds -DincludeModules="core.*,api.*"

Exclude test modules:

mvn osgi-utils:convert-blueprint-to-ds -DexcludeModules=".*test.*,.*demo.*"

Keep original files and process recursively:

mvn osgi-utils:convert-blueprint-to-ds -DkeepBlueprintFiles=true -Drecursive=true

Converting Apache Unomi

To convert Apache Unomi from Blueprint to DS:

1. Clone the Apache Unomi repository:

git clone https://github.com/apache/unomi.git
cd unomi

2. Add the plugin to the parent pom.xml:

<build>
    <pluginManagement>
        <plugins>
            <plugin>
                <groupId>dev.inoyu</groupId>
                <artifactId>osgi-utils-maven-plugin</artifactId>
                <version>1.3</version>
            </plugin>
        </plugins>
    </pluginManagement>
</build>

3. Add the plugin to each module that uses Blueprint:

<build>
    <plugins>
        <plugin>
            <groupId>dev.inoyu</groupId>
            <artifactId>osgi-utils-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>

4. Run the conversion on all modules:

mvn osgi-utils:convert-blueprint-to-ds -Drecursive=true

Conversion Details

The plugin performs the following conversions:

1. Services

   <service interface="com.example.Service">
     <service-properties>
       <entry key="property" value="value"/>
     </service-properties>
   </service>

   becomes:

   @Component(
       service = Service.class,
       property = {"property=value"}
   )

2. References

   <reference interface="com.example.Service"
              availability="optional"
              policy="dynamic">
     <reference-listener bind-method="bind" unbind-method="unbind"/>
   </reference>

   becomes:

   @Reference(
       service = Service.class,
       cardinality = ReferenceCardinality.OPTIONAL,
       policy = ReferencePolicy.DYNAMIC,
       bind = "bind",
       unbind = "unbind"
   )

3. Property Placeholders

   <cm:property-placeholder persistent-id="com.example">
     <cm:default-properties>
       <cm:property name="prop" value="value"/>
     </cm:default-properties>
   </cm:property-placeholder>

   becomes:

   @Component
   @Designate(ocd = Config.class)
   public class MyService {
       // ...
   }
   
   @ObjectClassDefinition
   public @interface Config {
       @AttributeDefinition
       String prop() default "value";
   }

4. Karaf Commands

   <shell:command-bundle>
     <shell:command name="example:cmd">
       <shell:action class="com.example.Command"/>
     </shell:command>
   </shell:command-bundle>

   becomes:

   @Service
   @Command(scope = "example", name = "cmd")
   public class Command implements Action {
       // ...
   }

Theme Support

The plugin supports both dark and light themes for better readability. You can set the theme using the theme system property:

# Use dark theme (default)
mvn osgi-utils:view-manifest -Dtheme=dark

# Use light theme
mvn osgi-utils:view-manifest -Dtheme=light

Parameters

The plugin supports the following parameters:

• package: The package name to search for or analyze (for locate-package and find-package-usages goals).
• jars: A comma-separated list of paths to JAR files to analyze (optional for view-manifest goal when used outside a project context).
• theme: Theme to use for output formatting (dark or light, default: dark).

Examples

1. Locate a package in a Maven project:

   mvn dev.inoyu:osgi-utils-maven-plugin:1.3:locate-package -Dpackage=org.osgi.framework

2. Analyze package usage in a Maven project:

   mvn dev.inoyu:osgi-utils-maven-plugin:1.3:find-package-usages -Dpackage=com.example.api

3. View manifest of the current Maven project:

   mvn dev.inoyu:osgi-utils-maven-plugin:1.3:view-manifest

4. View manifests of multiple JARs (can be used anywhere):

   mvn dev.inoyu:osgi-utils-maven-plugin:1.3:view-manifest -Djars=/path/to/bundle1.jar,/path/to/bundle2.jar

5. Validate Blueprint XML files:

   mvn dev.inoyu:osgi-utils-maven-plugin:1.3:validate-blueprint

6. Convert Blueprint to DS with custom configuration:

   mvn dev.inoyu:osgi-utils-maven-plugin:1.3:convert-blueprint-to-ds -Drecursive=true -DkeepBlueprintFiles=true

Best Practices

For Package Analysis

• Use locate-package to understand where packages are coming from
• Use find-package-usages to identify dependencies on specific packages
• Use view-manifest to inspect bundle metadata and dependencies

For Blueprint to DS Conversion

1. Before Conversion

   • Backup your codebase
   • Run all tests to establish baseline
   • Document current Blueprint configurations
   • Validate Blueprint files using the validation goal

2. During Conversion

   • Convert one module at a time
   • Verify each module after conversion
   • Run tests after each module conversion
   • Use keepBlueprintFiles=true initially for safety

3. After Conversion

   • Verify all services are properly registered
   • Check service properties and metadata
   • Validate configuration handling
   • Run full test suite
   • Remove Blueprint dependencies

For Blueprint Validation

• Run validation as part of your CI/CD pipeline
• Use failOnError=false during development for warnings only
• Address validation warnings to improve code quality

Troubleshooting

Package Analysis Issues

1. Package Not Found

   • Verify the package name is correct
   • Check if the package is in a different artifact
   • Use locate-package to find where the package is located

2. Manifest Issues

   • Use view-manifest to inspect the actual manifest content
   • Check for malformed headers or missing information

Blueprint to DS Conversion Issues

1. Missing Service Registration

   • Verify @Component annotation includes service attribute
   • Check service interface is correctly specified

2. Configuration Issues

   • Ensure @Designate annotation points to correct Config class
   • Verify property names match in Config interface

3. Reference Binding

   • Check cardinality matches Blueprint configuration
   • Verify bind/unbind methods are correctly specified

4. Karaf Commands

   • Ensure command scope and name match original Blueprint
   • Verify all command properties are preserved

Blueprint Validation Issues

1. XML Syntax Errors

   • Check for malformed XML
   • Verify namespace declarations
   • Ensure proper element nesting

2. Bean Property Errors

   • Verify Java classes exist and are accessible
   • Check property names match Java class fields
   • Ensure proper type compatibility

3. Reference Errors

   • Verify referenced services exist
   • Check interface compatibility
   • Ensure proper cardinality settings

For more complex issues, please file a bug report with:

• Original Blueprint XML (if applicable)
• Generated DS annotations (if applicable)
• Error messages or unexpected behavior
• Steps to reproduce
• Maven and Java versions

Contributing

Contributions to the Inoyu OSGi Utilities Maven Plugin are welcome! Please submit pull requests or open issues on our GitHub repository.

License

This project is licensed under the Apache License 2.0.