Collection of OSGi conversion tips

jars with xmlbeans compilation

To use xmlbeans generated code you need access to the SchemaTypeSystemImpl, which is not imported by the maven-bundle-plugin. So you need to add something like this to the pom:

Also, any package we may have with "impl" or "internal" needs to be explicitly listed in the Export-Packages.

If the xmlbeans compilation is to be used by an xmlbeans compilation in another bundle (for example, the "environment" element defined in the geronimo-service-builder compilation), extra steps are needed to make these available. In the defining bundle, all of the generated classes AND all of the packages under the schemaorg_apache_xmlbeans directory need to be exported. Because the bnd tool omits impl directories by default, these must be explicitly listed. Here's a sample from the geronimo-service-builder:

On the importing side, all of these classes need to be imported as well. The schemaorg_apache_xmlbeans directory is a bit
problematic because the bnd tool cannot handle wild-cards on the import unless the packages are explicitly referenced in the
code. The schemaorg packages are not referenced in the code and generate lot of cryptically named directories that are difficult to transfer over to the importing side. For the schemaorg directories, DynamicImport-Package can be used. This example is from the geronimo-connector-builder-1_6 plugin:

If the xmlbeans compilation is to be used by an xmlbeans compilation in another bundle (for example, the "environment" element defined in the geronimo-service-builder compilation), extra steps are needed to make these available. In the defining bundle, all of the generated classes AND all of the packages under the schemaorg_apache_xmlbeans directory need to be exported. Because the bnd tool omits impl directories by default, these must be explicitly listed. Here's a sample from the geronimo-service-builder:

On the importing side, all of these classes need to be imported as well. The schemaorg_apache_xmlbeans directory is a bit
problematic because the bnd tool cannot handle wild-cards on the import unless the packages are explicitly referenced in the
code. The schemaorg packages are not referenced in the code and generate lot of cryptically named directories that are difficult to transfer over to the importing side. For the schemaorg directories, DynamicImport-Package can be used. This example is from the geronimo-connector-builder-1_6 plugin:

Non-bundle interference

Many problems with building plugins are caused by non-bundle dependencies getting installed in felix rather than bundleized equivalents. Unfortuneately it looks like felix only says "non-framework bundles cannot be started" without telling us the location of the non-bundle. Running

helps to find the bad dependencies. On a related note, generally you have to exclude original jars from the dependencyManagement dependency entry of a bundleized repackaging. This seems like a serious defect in maven-bundle-plugin.

Assemble a server to make sure each set of plugins starts.

I think it's a good idea to assemble a server for each set of plugins to make sure they at least start. Here's how:

1. run
   where <foo> is your set of plugins
2. add it to svn
3. add the plugins you want to test as depedendencies
4. add this to start the server when run with -Pit
   in plugin management:
   and a profile

Note that at the moment the -Pit doesn't actually work, you have to try to start the server by hand

Classloading problems

Frequently, you'll see build problems with attempting to load a class when starting a configuration. Most of the time, this is caused by a bundle resolution problem that occurs earlier, but the information has been swallowed. If you use the -X option on the build, the resolution error will be given earlier in the build and you can generally figure out what's missing from that.

Occasionally, the resolution error will be a very generic "Constraint violation" without much information on what actually failed. Turning on debug logging in Felix will give some information, but I've found that building Felix with the following patch applied helps diagnose the problem more quickly:

Logging conversion

When converting plugins make sure to avoid the following dependencies: log4j, jcl-over-slf4j,
jul-to-slf4j, slf4j-api, or slf4j-log4j12. Instead use pax-logging-api. This bundle exports all of these logging API.

The pax-logging-api together with pax-logging-service provides a logging service in the OSGi environment that works with all commonly used logging API.

General OSGi tips

• The Bundle-ClassPath can refer to a directory within the bundle. Make sure there is an entry just for that directory in the JAR file of the bundle. Otherwise, classes might not be loaded from that directory.
• Always specify some wild mark in the filePattern (the second argument) in the bundle.findEntries() call to ensure the same set of entries is returned on different OSGi frameworks.