Maven groupId:artifactId and OSGi Bundle-SymbolicName - how they relate to each other?

OSGi massively coming to the maven world is a new trend, and is causing quite a big disturbance (at least to me).

First of all, as you already know, Fedora policies don't allow me to use binaries. Therefore Eclipse Orbit, a project that contains 3rd party Eclipse dependencies in the form of jars, is banned for me.

I witness that more and more open source jars support OSGi by default, but sometimes not exactly in the way I'd love to - especially if it comes to the naming schemes.

Let's look at the example of JDT core - the most widely used Eclipse jar. It was used as a maven dependency long before it received its official pom. As a result, it is available in Fedora with following aliases:

• org.eclipse:jdt.core

• org.eclipse.tycho:org.eclipse.jdt.core

• org.eclipse.jetty.orbit:org.eclipse.jdt.core

• org.eclipse.jdt:org.eclipse.jdt.core

The question is, which is the right one? Well, the OSGi Bundle-SymbolicName wiki page says that:

A BSN often takes the form of a reverse domain name. If automatically generated via Maven Bundle Plugin, takes the form ${pom.groupId}.${pom.artifactId}, or ${pom.artifactId} if it already starts with ${pom.groupId}.

So, in that case, we need to go the Maven Guide to Naming, and find out that:

groupId will identify your project uniquely across all projects, so we need to enforce a naming schema. It has to follow the package name rules, what means that has to be at least as a domain name you control, and you can create as many subgroups as you want. Look at More information about package names.

and

artifactId is the name of the jar without version. If you created it then you can choose whatever name you want with lowercase letters and no strange symbols. If it's a third party jar you have to take the name of the jar as it's distributed.

The artifactId for Eclipse should be a jar name, which in turn should follow Eclipse Naming conventions. The groupId should be a reverse domain name of the project, so in case of JDT, we would get org.eclipse.jdt, thus the final and proper groupId:artifactId of JDT core is org.eclipse.jdt:org.eclipse.jdt.core.



The real problem will appear if the project does not obey Maven guidelines, and has groupId:artifactId commons-logging:commons-logging or junit:junit. In that case applying OSGI guidelines will cause invalid Bundle-SymoblicNames: commons-logging and junit, which are against OSGi guidelines, although based on them.

In this situation it would be good to reconsider group and jar name changes to reflect the organization domain:

• org.apache.commons:logging (logging.jar shipped)
• org.junit:org.junit (org.junit.jar shipped).

Happy renaming!

Pre-indexing documentation with tycho

Older Eclipses had this irritating feature of indexing help on first access. I think that many of you remember that :-). The issue has been fixed in Eclipse 3.1. Wait. Actually only the mechanism to do the indexing at build time was delivered, and all content providers should have used it.

The indexing at build time was usually achieved by two steps:
1. Declare an extension saying where your index will be created:

<extension point="org.eclipse.help.toc">
   <index path="index">
   </index>
</extension>

2. Ensure that the index is actually built via customBuildCallbacks.xml

<project name="Build specific targets and properties" default="noDefault">
    <target name="post.build.jars">
        <help.buildHelpIndex manifest="plugin.xml" destination="."/>
    </target>
</project>

The problem with the customBuildCallbacks is that it allows for to much creativity, which is nearly as desired in build systems as in accountancy :). Thus it should not be used. So, the question is, how to make it work with maven? I wish the answer was simple, but I have no other choice then present it in the most brutal form of xml:

<build>
    <plugins>
        <plugin>
            <groupId>org.eclipse.tycho.extras
            <artifactId>tycho-eclipserun-plugin</artifactId>
            <!-- this is actually present in any 0.14+ version -->
            <version>0.16.0-SNAPSHOT</version>
            <configuration>
                <!-- this is to fix some lucene 3.x compatibility issue -->
		<argLine>-Dhelp.lucene.tokenizer=standard</argLine>
                <!-- actuall indexer call -->
		<appArgLine>-application org.eclipse.ant.core.antRunner -buildfile customBuildCallbacks.xml build.index</appArgLine>
                <dependencies>
                    <!-- list of bundles that we need -->
                    <dependency>
                        <artifactId>org.eclipse.ant.core</artifactId>
                        <type>eclipse-plugin</type>
                    </dependency>
		    <dependency>
                        <artifactId>org.apache.ant</artifactId>
                        <type>eclipse-plugin</type>
                    </dependency>
                    <dependency>
                        <artifactId>org.eclipse.help.base</artifactId>
                        <type>eclipse-plugin</type>
                    </dependency>
                </dependencies>
            </configuration>
            <executions>
                <execution>
                    <goals>
                        <goal>eclipse-run</goal>
                    </goals>
                    <phase>compile</phase>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

It should be read as: assemble an eclipse with org.apache.core,org.eclipse.ant.core, org.eclipse.help.base and all required dependencies, and then invoke the indexer. I hope this will be useful to someone during migration to tycho :-). Best regards Sources: Eclipse Help and Tycho wiki.